Частичная документация по API Swashbuckle Swagger C #

У меня есть проект веб-API с множеством сервисов. Изначально мы использовали стандартную документацию по API, которая поставляется с ASP.NET «из коробки».

Теперь я хочу перенести нашу документацию на Swagger. Я использую Swashbuckle. У меня есть очень специфические проблемы с документацией, которые я не хочу описывать.

Тем не менее, а также потому, что я хочу, чтобы мои документы swagger были чистыми и высококачественными, я хочу найти способ добавлять API-интерфейсы для Swagger один за другим.

Итак, главный вопрос: Могу ли я перейти на Swagger, постепенно добавляя новые API в документацию и оставляя старые документы нетронутыми?


asp.net-mvc swagger asp.net-web-api swashbuckle swagger-ui
person Andrei    schedule 16.03.2016    source источник
comment
Судя по тому, что я видел при использовании Swashbuckle, вы не можете переносить отдельные API. Но по моему опыту, как только вы начнете переносить свою документацию на Swagger, вы не пропустите старую документацию в стиле MVC.   -  person MichaelDotKnox    schedule 16.03.2016

Ответы (2)


arrow_upward
0
arrow_downward

Вы можете использовать ApiExplorerSettingsAttribute на контроллерах и методах, которые не должны отображаться в документации Swagger, как задокументировано здесь. Я предполагаю, что готовую документацию можно контролировать аналогичным образом (у меня нет опыта в этой части). Объединение этих двух функций позволяет постепенно перемещать документацию в Swagger.

person venerik    schedule 16.03.2016
comment
Проблема в том, что этот атрибут применяется как к swagger, так и к старой документации по веб-API. У меня, к сожалению, не работает. - person Andrei; 17.03.2016

arrow_upward
0
arrow_downward

Вы можете использовать атрибут [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);
}

Обратите внимание, что это только скрывает метод, он все еще может быть вызван. Если вы хотите перейти к следующему шагу, вам необходимо ввести фильтр аутентификации или авторизации.

person stevieg    schedule 13.10.2016