Question

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

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

那说，也因为我想保持我的招摇文档清洁和高质量，我想找到一种方法来逐个添加API。

所以，主要问题是：我可以迁移到swagger逐渐向文档中添加新的API并保持我的旧文档不受影响吗？

Answer 1

您可以将不希望在Swagger文档中显示的控制器和方法ApiExplorerSettingsAttribute用作documented here。我想开箱即用的文档可以用类似的方式控制（我没有这方面的经验）。结合这两个功能，您可以逐步将文档移动到Swagger。

Answer 2

您可以使用[Obsolete()]属性隐藏Swashbuckle中的方法。首先，您需要配置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);
}

请注意，这只隐藏方法，它仍然可以调用。如果您想进入下一步，则需要引入身份验证或授权过滤器。

C＃Swashbuckle Swagger部分API文档

2 个答案: