Язык программирования C#9 и платформа .NET5

        This is an example Get method returning JSON

     

    This is one of several examples for returning JSON:

       

        [

          "value1",

          "value2"

        ]

       

     

      List of strings   

 

На заметку! Если вы вводите три символа прямой косой черты перед определением класса или метода в Visual Studio, то среда создает начальную заглушку для XML-комментариев.

Далее необходимо объединить XML-комментарии со сгенерированным файлом swagger.json.

Добавление XML-комментариев в процесс генерации Swagger

Сгенерированные XML-комментарии должны быть добавлены в процесс генерации swagger.json. Начните с добавления следующих операторов using в файл класса Startup.cs:

using System.IO;

using System.Reflection;

Файл XML-документации добавляется в Swagger вызовом метода IncludeXmlComments() внутри метода AddSwaggerGen(). Перейдите к методу ConfigureServices() класса Startup и модифицируйте метод AddSwaggerGen(), добавив файл XML-документации:

services.AddSwaggerGen(c =>

{

  c.SwaggerDoc("v1",

    new OpenApiInfo

    {

      Title = "AutoLot Service",

      Version = "v1",

      Description = "Service to support the AutoLot dealer site",

      License = new OpenApiLicense

      {

        Name = "Skimedic Inc",

        Url = new Uri("http://www.skimedic.com")

      }

    });

    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";

    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);

    c.IncludeXmlComments(xmlPath);

});

Запустите приложение и загляните в пользовательский интерфейс Swagger. Обратите внимание на XML-комментарии, интегрированные в пользовательский интерфейс Swagger (рис. 30.4).

Помимо XML-документации документирование может быть улучшено дополнительной конфигурацией конечных точек приложения.

Дополнительные возможности документирования для конечных точек API

Существуют дополнительные атрибуты, которые дополняют документацию Swagger. Чтобы применить их, начните с добавления показанных далее операторов using в файл ValuesController.cs:

using Microsoft.AspNetCore.Http;

using Swashbuckle.AspNetCore.Annotations;

Атрибут Produces задает тип содержимого для конечной точки. Атрибут ProducesResponseType использует перечисление StatusCodes для указания возможного кода возврата для конечной точки. Модифицируйте метод Get() класса ValuesController, чтобы установить application/json в качестве возвращаемого типа и сообщить о том, что результатом действия будет либо 200 (ОК), либо 400 (Bad Request):

[HttpGet]

[Produces("application/json")]

[ProducesResponseType(StatusCodes.Status200OK)]

[ProducesResponseType(StatusCodes.Status400BadRequest)]

public ActionResult> Get()

{

  return new string[] {"value1", "value2"};

}

Хотя атрибут ProducesResponseType добавляет в документацию коды ответов, настроить эту информацию невозможно. К счастью, Swashbuckle добавляет атрибут SwaggerResponse, предназначенный как раз для такой цели. Приведите код метода Get() к следующему виду:

[HttpGet]

[Produces("application/json")]

[ProducesResponseType(StatusCodes.Status200OK)]

[ProducesResponseType(StatusCodes.Status400BadRequest)]

[SwaggerResponse(200, "The execution was successful")]

[SwaggerResponse(400, "The request was invalid")]

public ActionResult> Get()

{

  return new string[] {"value1", "value2"};

}

Прежде чем аннотации Swagger будут приняты и добавлены в сгенерированную документацию, их потребуется включить. Откройте файл Startup.cs и перейдите к методу Configure(). Обновите вызов AddSwaggerGen(), как показано ниже:

services.AddSwaggerGen(c =>

{

  c.EnableAnnotations();

  ...

});