Документирование

В этом документе я только введу в курс дела о том что из себя представляет документирование в ASP .Net Core Web API. По этой теме очень много деталей, которые можно расписать на много страниц. Но если хотите все это узнать, то рекомендую прочитать эту статью:

Хабр — Документирование ASP .Net Core Web API с помощью OpenAPI/Swagger. Библиотека Swashbuckle

Swagger

Swagger — это популярный набор инструментов и спецификаций для документирования, проектирования и тестирования API, в основном ориентированных на RESTful API. С его помощью можно автоматически генерировать документацию для API. Вот как это может выглядеть:

Настройка приложения

• Устанавливаем пакет Swashbuckle.AspNetCore (может быть установлен по умолчанию, если при создании проекта была включена галочка Enable OpenAPI Support).

• Конфигурируем Swagger в Program:

public static void ConfigureSwager(this IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1.1",
            new OpenApiInfo
            {
                Title = "Demo API - V1",
                Version = "v1.1"
            }
         );

        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}

public static void ConfigureSwagger(this IApplicationBuilder app)
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1.1/swagger.json", "Demo Web API V1.1");
    });
}

var builder = WebApplication.CreateBuilder(args);

...

builder.Services.ConfigureSwager();

...

var app = builder.Build();

...

if (app.Environment.IsDevelopment())
{
    app.ConfigureSwagger();
}

В данном примере страница со Swagger будет отображаться только в Development среде.

• Открываем файл основного проекта (*.csproj) и добавляем следующую строку:

<GenerateDocumentationFile>True</GenerateDocumentationFile>

• Запускаем приложение и переходим на страницу localhost:8080/swagger (этот адрес приведен для примера. Если у вас приложение запущено не на локалхосте или на другом порту, то адрес будет другой). На открытой странице должны отображаться все контроллеры и endpoint'ы. Можно раскрыть любой endpoint и попробовать протестировать его.

Документирование

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

/// <summary>
/// Provides access to map download.
/// </summary>
/// <param name="mapId">Map identifier</param>
/// <returns>Download url</returns>
/// <response code="200">Returns download url</response>
/// <response code="400">If map not found</response>
/// <response code="401">If authorization error</response>
[Authorize]
[HttpPost("download/{mapId}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status401Unauthorized)]
public async Task<IActionResult> Download(string mapId)
{ ... }

Для большей информации о том как документировать API читайте по приведенной ссылке.

Ссылки

Хабр — Документирование ASP .Net Core Web API с помощью OpenAPI/Swagger. Библиотека Swashbuckle

Автор документа: Артём Ветик