c# - studio - Cómo omitir métodos de la documentación de Swagger en WebAPI usando Swashbuckle

swashbuckle swagger

Question

Tengo una aplicación C # ASP.NET WebAPI con documentación de API que se genera automáticamente usando Swashbuckle . Quiero poder omitir ciertos métodos de la documentación, pero parece que no puedo resolver cómo decirle a Swagger que no los incluya en la salida de la interfaz de usuario de Swagger.

Tengo la sensación de que tiene algo que ver con agregar un modelo o filtro de esquema, pero no es obvio qué hacer y la documentación solo parece proporcionar ejemplos de cómo modificar la salida de un método, no eliminarlo por completo de la salida.

Gracias por adelantado.

Answer 1

Alguien publicó la solución en github, así que voy a pegarla aquí. Todos los créditos van a él. https://github.com/domaindrivendev/Swashbuckle/issues/153#issuecomment-213342771

Crear primero una clase de atributo

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

Luego cree una clase de filtro de documentos

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);
        }
    }
}

Luego, en la clase Swagger Config, agregue ese filtro de documentos

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

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

El último paso es agregar el atributo [HideInDocsAttribute] en el Controlador o Método que no desea que Swashbuckle genere documentación.

Answer 2

Basado en la answer @spottedmahns. Mi tarea era viceversa. Mostrar solo los que están permitidos.

Marcos: .NetCore 2.1; Swagger: 3.0.0

Atributo agregado

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

E implementar IDocumentFilter personalizado

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);
            }
        }
    }
}

Código de ConfigureServices :

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

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

Answer 3

Hacer un filtro

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);
            }
        }
    }
}

Hacer un atributo

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

Aplicar en startup.cs

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

Agregue el atributo [SwaggerTag] a los métodos y controladores que desea incluir en Swagger JSON

Answer 4

Preferiría eliminar completamente las entradas del diccionario para elementos de ruta:

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

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

Con este enfoque, no obtendría elementos "vacíos" en la definición generada de swagger.json.

Answer 5

Puede agregar el siguiente atributo a Controladores y Acciones para excluirlos de la documentación generada: [ApiExplorerSettings(IgnoreApi = true)]

Answer 6

Puede eliminar las "operaciones" del documento swagger después de que se haya generado con un filtro de documentos; simplemente establezca el verbo en null (aunque también puede haber otras formas de hacerlo)

La siguiente muestra solo permite verbos GET , y se toma de este problema .

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;
        }
    }
}

y en tu configuración de swagger:

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

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