Добавление документации OpenAPI с помощью аннотаций и комментариев XML

  • 4 мин

Пользовательский интерфейс Swagger позволяет взаимодействовать с ресурсами API и визуализировать их, не требуя доступа к исходному коду. Из спецификации OpenAPI графическое представление API создается автоматически. Это облегчает другим разработчикам создание приложений, для которых требуются API.

Swagger UI четко визуализирует операции и методы, как показано на рисунке ниже.

Operations of API in Swagger UI.

Пользовательский интерфейс Swagger позволяет взаимодействовать, а также попробовать каждую из операций.

Interaction with API Operation in Swagger UI.

Автоматическое создание документации API с помощью средств Swagger и Swashbuckle поможет сторонним производителям разобраться в ресурсах API. Что случится, если потребуется продвинутся немного далее и предоставить дополнительные сведения? Вам потребуется вся возможная информация при первом использовании API.

Комментарии XML

Включение комментариев XML позволяет создать документацию кода. Эти комментарии следует поместить перед комментируемым блоком кода.

/// <summary>
/// Returns a group of Employees matching the given first and last names.
/// </summary>
/// <remarks>
/// Here is a sample remarks placeholder.
/// </remarks>
/// <param name="firstName">The first name to search for</param>
/// <param name="lastName">The last name to search for</param>
/// <returns>A string status</returns>
[HttpGet]
[Route("byname/{firstName}/{lastName}")]
public ActionResult<string> GetByName(string firstName, string lastName)
{
    return "Found another University employee";
}

Ниже приведен пример использования узлов XML.

  • Сводка. Общие сведения о том, что такое метод, класс или поле.
  • комментарии: Дополнительные сведения о методе/классе/поле.
  • param: параметр метода и то, что он представляет.
  • возвращает: описание возвращаемого метода.

После включения xml-комментариев средство Swashbuckle может включать комментарии xml-документации в документацию OpenAPI и позволяет просматривать его в пользовательском интерфейсе Swagger.

Image showing Swagger UI and added XML Comments.

Аннотирование данных

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

Например, если добавить к контроллеру следующую аннотацию,

[Produces("application/json")]

... в пользовательском интерфейсе Swagger отображаются добавленные сведения:

Image showing Swagger UI with added content type added to annotations.

Советы

Существует несколько заметок к данным, которые следует использовать при описании API.

  • Определите, какой тип содержимого content-types API обрабатывает в запросах и ответах. Следующие атрибуты указывают, что API должен использовать application/json только тип контента в обоих направлениях.

    [Produces("application/json")]
[Consumes("application/json")]

  • Определите потенциальные коды HTTP-ответов, которые могут возвращаться вызывающему клиенту. Следующий атрибут показывает API, который может возвращать ошибку 404 (Не найдено).

    [ProducesResponseType(StatusCodes.Status404NotFound)]

    Api может создать стандартный набор кодов откликов, в этом случае можно использовать следующий атрибут, чтобы указать 200, 400 и 404 вместо указания каждого отдельно. Дополнительные сведения об использовании соглашений о веб-API.

    [ApiConventionMethod(typeof(DefaultApiConventions))]

  • Создайте operationId, чтобы значительно улучшить возможности использования API, включая документирование, создание кода и интеграцию с другими службами. Вы можете автоматически создать operationId, включив свойство Name в фильтр HTTP-команды.

    [HttpGet("{Height}/{Width}", Name="GetPrice")]