Як опустити методи з документації Swagger на WebAPI за допомогою Swashbuckle


135

У мене додаток C # ASP.NET WebAPI з документацією API автоматично генерується за допомогою Swashbuckle . Я хочу мати можливість опустити певні методи з документації, але я не можу зрозуміти, як сказати Swagger не включати їх у вихідний інтерфейс Swagger.

Я вважаю, що це щось пов'язане з додаванням моделі або фільтра схеми, але не очевидно, що робити, і документація лише здається, що надає приклади того, як змінити результат для методу, а не видалити його повністю з виводу.

Заздалегідь спасибі.

Відповіді:


337

Ви можете додати наступний атрибут до контролерів та дій, щоб виключити їх із створеної документації: [ApiExplorerSettings(IgnoreApi = true)]


12
Працювало чудово, на це має бути відповідь
JohnC

4
Чи є спосіб це зробити програмно? Я хочу розкрити API в одних середовищах, але не в інших, відповідно до налаштувань конфігурації.
Пол Кієніц

@SyaifulNizamYahya Не впевнений. Може, [JsonIgnore]?
mikesigs

@mikesigs Так [JsonIgnore] працює. На жаль, він забороняє серіалізацію.
Syaiful Nizam Yahya

4
Документація з підключення: Опустіть довільні операції
плямистого числа

17

Хтось розмістив рішення на github, тому я збираюся вставити його сюди. Всі кредити йому належать. https://github.com/domaindrivendev/Swashbuckle/isissue/153#issuecomment-213342771

Створіть перший клас атрибутів

[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 =>
                {
                    ...
                });
    }
}

Останній крок - додати атрибут [HideInDocsAttribute] на контролер або метод, який ви не хочете, щоб Swashbuckle генерував документацію.


1
Я думаю, що RemoveRoute може бути дроїдом, якого я шукаю.
Пол Кієніц

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

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.


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


Солодке. Відповідний підхід і дякую за те, що ви поділилися.
Ведран Мандич

2

Може допомогти комусь, але під час розробки (налагодження) ми хотіли б викрити цілі контролери та / або дії, а потім приховати їх під час виробництва (складання випуску)

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

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 code:

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

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

Дякую Алеха. Цей підхід насправді добре працює для SwashBuckle.OData, де ApiExplorerSettingsAttribute не працює.
Прасад Корхале

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

0

Додайте це поверх своїх методів, які ви хочете опустити,

[ApiExplorerSettings(IgnoreApi=true)]
Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.