Использование Swagger в ASP.NET Core

Когда вы разрабатываете проект, всегда возникает необходимость составления документации и поддержании её в актуальном виде. Решать эту проблему можно по-разному, обычно применяются возможности авто документирования, это позволяет при минимальных временных затратах получить достаточно качественную документацию, которая всегда будет соответствовать актуальной версии вашего API. В настоящее время очень популярным и функциональным фреймворком для работы с API является Swagger, о нем и хочу рассказать в данной статье.

Давайте создадим ASP.NET Core API приложение. По умолчанию в проект добавлен контроллер ValuesController, который уже содержит примеры использования вызовов API.

Для работы со Swagger необходимо установить библиотеку Swashbuckle.AspNetCore

PM > Install-Package Swashbuckle.AspNetCore
Подключение библиотеки Swashbuckle.AspNetCore

Теперь нужно зайти в файл Startup.cs, перейти в ConfigureServices и добавить AddSwaggerGen, метод будет выглядеть следующим образом:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info
        {
            Version = "v1",
            Title = "Test API",
            Description = "ASP.NET Core Web API"
        });
    });
}

После этого добавим Swagger UI в метод Configure, после чего он будет выглядеть следующим образом:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseMvc();


    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API V1");
    });
}

Запустим полученное приложение и перейдём по адресу /swagger

Отображение документации API в Swagger

Если я добавлю новый контроллер, например UsersController, добавлю методы для работы с данными пользователей, то он автоматически начнёт отображаться здесь:

Отображение данных нового контроллера API в Swagger

Вы можете увидеть какие модели используются в API, какие параметры обязательны, какие нет. Также прямо здесь можно протестировать работу ваших методов, для этого нужно выбрать нужный метод и нажать Try it out:

Выполнение метода API в Swagger

Используемая модель UserDto выглядит следующим образом:

public class UserDto
{
    [JsonIgnore]
    public Guid Id { get; set; }

    [Required]
    public string FirstName { get; set; }

    [Required]
    public string LastName { get; set; }

    [Required]
    [JsonProperty(PropertyName = "mobilePhone")]
    public string Phone { get; set; }

    public string Email { get; set; }
}

Здесь можно заметить, что можно использовать различные привычные для всех атрибуты, которые отлично понимаются и обрабатываются в Swagger.

Использование XML комментариев

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

В конфигурации проекта зайти в раздел Build и в подразделе Output установить "XML documentation file". Задав путь, по которому будет сохраняться XML файл

Сохранение XML документации в файл в ASP.NET Core

После этого зайти в метод ConfigureServices класса Startup и в AddSwaggerGen добавить c.IncludeXmlComments(GetXmlCommentsPath()) подключение будет выглядеть следующим образом:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Version = "v1",
        Title = "Test API",
        Description = "ASP.NET Core Web API"
    });
    c.IncludeXmlComments(GetXmlCommentsPath());

});

Метод GetXmlCommentsPath выглядит следующим образом:

private static string GetXmlCommentsPath()
{
    return String.Format(@"{0}\SwaggerTest.XML", AppDomain.CurrentDomain.BaseDirectory);
}

После этого можно увидеть, что описание для методов и их параметров начало отображаться:

Отображение описаний методов и переменных в Swagger

Использование в Postman

Еще очень удобно импортировать json который генерирует swagger в Postman.

Для импорта всего лишь необходимо вставить ссылку на json файл

Добавление файла для импорта в Postman

После этого в  Postman будут доступны все имеющиеся методы. Те методы, для которых было задано описание будут подписаны, что добавляет удобства работы с ними.

Отображение импортируемых файлов в Postman

В настоящее время Swagger может работать с более чем 25 языками программирования, так что использование не ограничено одним лишь .NET Core, он может быть полезен практически в любых проектах, в которых создаётся API.

Более детально со Swagger можно ознакомиться на сайте.

Приятного программирования.

Комментарии (1) -

Алексей 06.06.2018 11:38:07

Отличная статья, очень удобный подход к API с использованием Blazor.

Добавить комментарий