C# Swashbuckle Swagger 部分 API 文档

Question

我有一个包含大量服务的Web API项目。最初，我们使用开箱即用的标准 API 文档 ASP.NET。

现在我想将我们的文档迁移到 Swagger。我使用虚张声势。我在文档中遇到了一些我不想描述的非常具体的问题。

话虽如此，也因为我想保持我的招摇文档干净和高质量，我想找到一种方法来添加 API 以一个接一个地招摇。

因此，主要问题是：我是否可以迁移到大摇大摆地逐步向文档中添加新 API 并保持旧文档不变？

Answer 1

您可以在不希望

出现在 Swagger 文档中的控制器和方法上使用ApiExplorerSettingsAttribute，如此处所述。我想开箱即用的文档可以用类似的方式控制（我在这方面没有任何经验）。结合这两个功能，您可以将文档逐渐移动到 Swagger。

Answer 2

您可以使用 [Obsolete()] 属性在 Swashbuckle 中隐藏方法。首先，您需要配置您的虚张声势，以便在构建 Swagger 文档时查找此属性：

config.EnableSwagger(
    routePrefix + "docs/{apiVersion}/swagger",
    c =>
    {
        // Set this flag to omit descriptions for any actions decorated with the Obsolete attribute
        c.IgnoreObsoleteActions();
        // Set this flag to omit schema property descriptions for any type properties decorated with the
        c.IgnoreObsoleteProperties();
    });

然后装饰您想要隐藏的操作：

[Obsolete("Hidden from Swashbuckle during renovations")]
[HttpGet]
Task<object> async WhyILostMyJob(string query)
{
     return await Database.SqlExecAsync(query, isAdmin: true);
}

请注意，这只会隐藏方法，它仍然是可调用的。如果要将其进行下一步，则需要引入身份验证或授权筛选器。