Swagger - gro1vy/DeliverServiceAPI GitHub Wiki

Swagger — это набор инструментов, который позволяет автоматически описывать API на основе его кода. Документация, автоматически созданная через Swagger, облегчает понимание API для компьютеров и людей.

На основе кода или набора правил Swagger автоматически генерирует документацию в формате JSON-файла. Ее можно встроить на страницу сайта или в приложение, чтобы пользователи могли интерактивно знакомиться с документацией, можно отправлять клиентам — сгенерировать такое описание намного быстрее, чем написать с нуля.

Основное назначение Swagger это быстрая и лёгкая автоматическая генерация документация, которую к тому же можно дописывать самостоятельно. Соответсвенно такая документация позволяет пользователям нашего API быстро понять, как с ним работать.

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

Swagger «читает» код API и на его основе генерирует документацию, и хоть swagger и укажет контроллеры, его методы, что эти методы могут вернуть (тип, возвращаемый методом) и как к ним обратиться, но без дополнительного описания от разработчика API, документация будет не до конца подробной. И в asp.net есть несколько способов добавления этого дополнительного описания.

Первый способ с помощью атрибута ProducesResponseType, который показывает, какой код может вернуть метод помимо кода 200 и какую модель с этим кодом пришлет.

Вот несколько примером:

• [ProducesResponseType(StatusCodes.Status400BadRequest)] - указывает, что метод может вернуть код 400, а так как возвращаемая модель не указана, то в зависимости от кода Swagger либо покажет стандартную модель, либо ничего не укажет
• [ProducesResponseType(typeof(ResponseDTO), StatusCodes.Status400BadRequest)] - указывает, что метод может вернуть код 400, с которым придет модель ResponseDTO

С помощью второго способа можно задавать возвращаемые код и их описание, однако без указания возвращаемой модели, а также давать описание для метода.

Для того, чтобы воспользоваться данным способом нужно настроить проект и немного модифицировать Swagger.

Итак в конфигурацию проекта нужно добавить следующие строки, чтобы Swagger смод получить доступ к XML Comments у методов:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

После в Program.cs в добавить для модификации Swagger:

builder.Services.AddSwaggerGen(options =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);
});

Теперь, когда проект настроен, можно у методов XML Comments и они будут отображаться в Swagger.

Добавим для метода описание:

/// <summary>
/// Get user profile
/// </summary>
/// <remarks>
/// Any text
/// </remarks>
/// <response code="401">Unauthorized</response>
[HttpPut("profile")]
public async Task<ActionResult> EditUserInfo([FromBody] UserEditRequestDTO model)
{
  // Code
}

Тогда получим такое описание:

Итак в теге