如何使用Swashbuckle在WebAPI上从Swagger文档中省略方法

134

我有一个C＃ASP.NET WebAPI应用程序，带有使用Swashbuckle自动生成的API文档。我希望能够从文档中省略某些方法，但似乎无法弄清楚如何告诉Swagger不要将它们包括在Swagger UI输出中。

我感觉这与添加模型或模式过滤器有关，但操作不明显，文档似乎仅提供了如何修改方法输出的示例，而不是将其从输出中完全删除。

提前致谢。

c# asp.net .net swagger

— 史蒂夫·威尔金森
source

336

您可以将以下属性添加到Controllers and Actions，以将其从生成的文档中排除： [ApiExplorerSettings(IgnoreApi = true)]

— 米克西格斯
source

12

— 做得

4

有办法以编程方式执行此操作吗？根据配置设置，我想在某些环境中公开API，但在其他环境中则不公开。

— Paul Kienitz '18

@SyaifulNizamYahya不确定。也许[JsonIgnore]？

— mikesigs

@mikesigs是[JsonIgnore]有效。不幸的是，它禁止序列化。

— Syaiful Nizam Yahya

4

Swashbuckle文档：省略任意操作

— spottedmahn

17

有人在github上发布了解决方案，所以我将其粘贴到这里。所有的功劳归他所有。https://github.com/domaindrivendev/Swashbuckle/issues/153#issuecomment-213342771

首先创建一个Attribute类

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class HideInDocsAttribute : Attribute
{
}

然后创建一个文档过滤器类

public class HideInDocsFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        foreach (var apiDescription in apiExplorer.ApiDescriptions)
        {
            if (!apiDescription.ActionDescriptor.ControllerDescriptor.GetCustomAttributes<HideInDocsAttribute>().Any() && !apiDescription.ActionDescriptor.GetCustomAttributes<HideInDocsAttribute>().Any()) continue;
            var route = "/" + apiDescription.Route.RouteTemplate.TrimEnd('/');
            swaggerDoc.paths.Remove(route);
        }
    }
}

然后在Swagger Config类中，添加该文档过滤器

public class SwaggerConfig
{
    public static void Register(HttpConfiguration config)
    {
        var thisAssembly = typeof(SwaggerConfig).Assembly;

        config
             .EnableSwagger(c =>
                {
                    ...                       
                    c.DocumentFilter<HideInDocsFilter>();
                    ...
                })
            .EnableSwaggerUi(c =>
                {
                    ...
                });
    }
}

最后一步是在您不希望Swashbuckle生成文档的Controller或Method上添加[HideInDocsAttribute]属性。

— 保罗·波兹蒂
source

1

我认为RemoveRoute可能是我要寻找的机器人。

— Paul Kienitz '18

13

您可以在使用文档过滤器生成的招摇文档中删除“操作”，只需将动词设置为 null（尽管也可以使用其他方式）

下面的示例仅允许GET动词-并从此问题中获取。

class RemoveVerbsFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        foreach (PathItem path in swaggerDoc.paths.Values)
        {
            path.delete = null;
            //path.get = null; // leaving GET in
            path.head = null;
            path.options = null;
            path.patch = null;
            path.post = null;
            path.put = null;
        }
    }
}

并在您昂首阔步的配置中：

...EnableSwagger(conf => 
{
    // ...

    conf.DocumentFilter<RemoveVerbsFilter>();
});

— 戴夫横梁
source

1

请注意：即使您取消注释，也不会删除路径path.get = null;-因此，这些路径仍将包含在Swagger文件中，但没有详细信息。ApiExplorerSettingsAttribute如您在GitHub上的原始回复中提到的那样，最好将其包含在您的答案中。使用ApiExplorerSettings还可避免将类型信息添加到Swagger文件的schemes列表中。

— JBert

7

我希望完全删除路径项的字典条目：

var pathsToRemove = swaggerDoc.Paths
                .Where(pathItem => !pathItem.Key.Contains("api/"))
                .ToList();

foreach (var item in pathsToRemove)
{
    swaggerDoc.Paths.Remove(item.Key);
}

使用这种方法，您将不会在生成的swagger.json定义中获得“空”项目。

— 丹尼斯·比昂迪克（Denis Biondic）
source

3

制作一个过滤器

public class SwaggerTagFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach(var contextApiDescription in context.ApiDescriptions)
        {
            var actionDescriptor = (ControllerActionDescriptor)contextApiDescription.ActionDescriptor;

    if(!actionDescriptor.ControllerTypeInfo.GetCustomAttributes<SwaggerTagAttribute>().Any() && 
    !actionDescriptor.MethodInfo.GetCustomAttributes<SwaggerTagAttribute>().Any())
            {
                var key = "/" + contextApiDescription.RelativePath.TrimEnd('/');
            swaggerDoc.Paths.Remove(key);
            }
        }
    }
}

设定一个属性

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class SwaggerTagAttribute : Attribute
{
}

应用于startup.cs

 services.AddSwaggerGen(c => {
            c.SwaggerDoc(1,
                new Info { Title = "API_NAME", Version = "API_VERSION" });
            c.DocumentFilter<SwaggerTagFilter>(); // [SwaggerTag]
        });

将[SwaggerTag]属性添加到要包含在Swagger JSON中的方法和控制器中

— 罗恩·斯金格
source

甜。适当的方法，感谢您分享sln。

— VedranMandić，

2

可能对某人有帮助，但在开发（调试）期间，我们希望公开整个Controller和/或Action，然后在生产期间将其隐藏（发行版本）

#if DEBUG
    [ApiExplorerSettings(IgnoreApi = false)]
#else
    [ApiExplorerSettings(IgnoreApi = true)]
#endif

— 索伦·佩德森（Soeren Pedersen）
source

1

基于@spottedmahns 答案。反之亦然。仅显示允许的那些。

框架：.NetCore 2.1；摇摇欲坠：3.0.0

新增属性

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class ShowInSwaggerAttribute : Attribute
{
}

并实现自定义IDocumentFilter

public class ShowInSwaggerFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {

        foreach (var contextApiDescription in context.ApiDescriptions)
        {
            var actionDescriptor = (ControllerActionDescriptor) contextApiDescription.ActionDescriptor;

            if (actionDescriptor.ControllerTypeInfo.GetCustomAttributes<ShowInSwaggerAttribute>().Any() ||
                actionDescriptor.MethodInfo.GetCustomAttributes<ShowInSwaggerAttribute>().Any())
            {
                continue;
            }
            else
            {
                var key = "/" + contextApiDescription.RelativePath.TrimEnd('/');
                var pathItem = swaggerDoc.Paths[key];
                if(pathItem == null)
                    continue;

                switch (contextApiDescription.HttpMethod.ToUpper())
                {
                    case "GET":
                        pathItem.Get = null;
                        break;
                    case "POST":
                        pathItem.Post = null;
                        break;
                    case "PUT":
                        pathItem.Put = null;
                        break;
                    case "DELETE":
                        pathItem.Delete = null;
                        break;
                }

                if (pathItem.Get == null  // ignore other methods
                    && pathItem.Post == null 
                    && pathItem.Put == null 
                    && pathItem.Delete == null)
                    swaggerDoc.Paths.Remove(key);
            }
        }
    }
}

ConfigureServices代码：

public void ConfigureServices(IServiceCollection services)
{
     // other code

    services.AddSwaggerGen(c =>
    {
        // other configurations
        c.DocumentFilter<ShowInSwaggerFilter>();
    });
}

— 阿莱哈
source

谢谢阿莱哈。这种方法实际上对于SwashBuckle.OData效果很好，其中ApiExplorerSettingsAttribute不起作用。

— Prasad Korhale

1

添加一行SwaggerConfig c.DocumentFilter（）;

public class HideInDocsFilter : IDocumentFilter
    {
        public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
        { 
var pathsToRemove = swaggerDoc.Paths
                .Where(pathItem => !pathItem.Key.Contains("api/"))
                .ToList();

foreach (var item in pathsToRemove)
{
    swaggerDoc.Paths.Remove(item.Key);
}
    }
}

— 维克拉米
source

0

将此添加到您要忽略的方法之上-

[ApiExplorerSettings(IgnoreApi=true)]

— Mridusmita Deka
source