web-dev-qa-db-fra.com

Comment omettre des méthodes de la documentation Swagger sur les API Web à l'aide de Swashbuckle

J'ai une application WebAPI C # ASP.NET avec une documentation d'API générée automatiquement à l'aide de Swashbuckle . Je veux pouvoir omettre certaines méthodes de la documentation, mais je n'arrive pas à comprendre comment dire à Swagger de ne pas les inclure dans la sortie de l'interface utilisateur de Swagger. 

Je sens que cela a quelque chose à voir avec l’ajout d’un filtre de modèle ou de schéma, mais il n’est pas évident de savoir quoi faire et la documentation ne semble fournir que des exemples de la façon de modifier le résultat d’une méthode et non de le supprimer complètement. le résultat.

Merci d'avance.

c#asp.net.netswagger
66
SteveWilkinson

Vous pouvez ajouter l'attribut suivant aux contrôleurs et aux actions pour les exclure de la documentation générée: [ApiExplorerSettings(IgnoreApi = true)]

150
mikesigs

Vous pouvez supprimer les "opérations" du document swagger après qu'il ait été généré avec un filtre de document - définissez simplement le verbe sur null (bien qu'il puisse exister d'autres moyens de le faire)

L'exemple suivant autorise uniquement les verbes GET - et provient de this issue .

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

et dans votre configuration de swagger:

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

    conf.DocumentFilter<RemoveVerbsFilter>();
});
11
Dave Transom

Quelqu'un a posté la solution sur github alors je vais la coller ici. Tous les crédits vont à lui. https://github.com/domaindrivendev/Swashbuckle/issues/153#issuecomment-213342771

Créer d'abord une classe d'attribut

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

Puis créez une classe de filtre de document

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

Ensuite, dans la classe Swagger Config, ajoutez ce filtre de document

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

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

La dernière étape consiste à ajouter l'attribut [HideInDocsAttribute] sur le contrôleur ou la méthode que vous ne souhaitez pas que Swashbuckle génère de la documentation.

9
Paulo Pozeti

Faire un filtre

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

Faire un attribut

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

Appliquer dans startup.cs

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

Ajouter l'attribut [SwaggerTag] aux méthodes et aux contrôleurs que vous souhaitez inclure dans Swagger JSON

1
Rowan Stringer

Je préférerais supprimer complètement les entrées du dictionnaire pour les éléments de chemin d'accès: 

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

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

Avec cette approche, vous n'obtiendrez pas d'éléments "vides" dans la définition swagger.json générée.

1
Denis Biondic

Basé sur @spottedmahns answer . Ma tâche était inversement Afficher uniquement ceux qui sont autorisés.

Cadres: .NetCore 2.1; Swagger: 3.0.0

Attribut ajouté 

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

Et implémenter personnalisé 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 code:

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

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