Как настроить swagger под проект

Документирование API с помощью OpenAPI 3 и Swagger

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

Веб-приложение часто содержит API для взаимодействия с ним. Документирование API позволит клиентам быстрее понять, как использовать ваши сервисы. Если API закрыт от внешнего мира, то все равно стоит уделить время спецификации — это поможет вашим новым коллегам быстрее разобраться с системой.

Создание документации вручную — утомительный процесс. Swagger поможет вам упростить эту работу.

Что такое Swagger?

Swagger автоматически генерирует спецификацию вашего API в виде json. А проект Springdoc создаст удобный UI для визуализации. Вы не только сможете просматривать документацию, но и отправлять запросы, и получать ответы.

Также возможно сгенерировать непосредственно клиента или сервер по спецификации API Swagger, для этого нужен генератор кода Swagger-Codegen.

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

Вы найдете все примеры представленные тут в моем репозитории.

Создание REST API

Чтобы документировать API, для начала напишем его 😄 Вы можете перейти к следующей главе, чтобы не тратить время.

Добавим примитивные контроллеры и одно DTO. Суть нашей системы – программа лояльности пользователей.

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

В качестве DTO у нас будет класс UserDto – это пользователь нашей системы. У него пять полей, из которых 3 обязательны:

• имя
• уникальный ключ
• пол пользователя
• количество баллов
• дата регистрации

Для взаимодействия с нашей бизнес-логикой, добавим три контроллера: UserController , PointContoller , SecretContoller .

UserController отвечает за добавление, обновление и получение пользователей.

PointContoller отвечает за взаимодействие с баллами пользователя. Один метод этого контроллера отвечает за добавление и удаление балов пользователям.

Метод destroy в SecretContoller может удалить всех пользователей.

Настраиваем Swagger

Теперь добавим Swagger в наш проект. Для этого добавьте следующие зависимости в проект.

Swagger автоматически находит список всех контроллеров, определенных в нашем приложении. При нажатии на любой из них будут перечислены допустимые методы HTTP (DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT).

Для каждого метода доступные следующие данные: статус ответа, тип содержимого и список параметров.

Поэтому после добавления зависимостей, у нас уже есть документация. Чтобы убедиться в этом, переходим по адресу: localhost:8080/swagger-ui.html

Swagger запущенный с дефолтными настройками

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

Пока у нас не очень информативная документация. Давайте исправим это.

Для начала создадим класс конфигурации сваггера SwaggerConfig — имя произвольное.

• title – это название вашего приложения
• version – версия вашего API

Эти данные больше для визуальной красоты UI документации.

Добавление авторов

Добавьте разработчиков API, чтобы было понятно, кто в ответе за это безобразие 😄

Разметка контроллеров

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

Скрыть контроллер

У нас есть контроллер, который мы хотим скрыть – SecretController . Аннотация @Hidden поможет нам в этом.

Аннотация скрывает контроллер только из Swagger. Он все также доступен для вызова. Используйте другие методы для защиты вашего API.

Наша документация стала намного понятнее, но давайте добавим описания для каждого метода контроллера.

Разметка методов

Аннотация @Operation описывает возможности методов контроллера. Достаточно определить следующие значения:

• summary – короткое описание.
• description – более полное описание.

Разметка переменных метода

При помощи аннотации Parameter также опишем переменные в методе, который отвечает за управление баллами пользователей.

С помощью параметра required можно задать обязательные поля для запроса. По умолчанию все поля необязательные.

Разметка DTO

Разработчики стараются называть переменные в классе понятными именами, но не всегда это помогает. Вы можете дать человеко-понятное описание самой DTO и ее переменным с помощью аннотации @Schema .

Сваггер заполнит переменные, формат которых он понимает: enum, даты. Но если некоторые поля DTO имеют специфичный формат, то помогите разработчикам добавив пример.

Выглядеть это будет так:

Но подождите, зачем мы передаем дату регистрации. Да и уникальный ключ чаще всего будет задаваться сервером. Скроем эти поля из swagger с помощью параметра Schema.AccessMode.READ_ONLY :

Валидация

Добавим валидацию в метод управления баллами пользователя в PointController . Мы не хотим, чтобы можно было передать отрицательные баллы.

Давайте посмотрим на изменения спецификации.

Для поля point появилось замечание minimum: 0 .

И все это нам не стоило ни малейшего дополнительного усилия.

Этих аннотаций вам хватит, чтобы сделать хорошее описание API вашего проекта.

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

Источник

ASP.NET Core: Создание справочных страниц веб-API ASP.NET с помощью Swagger

При создании высоконагруженных приложений бывает сложно разобраться в различных API. Сформировать качественную документацию и справочные страницы в рамках веб-API посредством Swagger с интеграцией Swashbuckle .NET Core так же просто, как добавить пару пакетов NuGet и изменить Startup.cs.

Второй цикл статей по ASP.NET Core

Введение

Для начала поговорим о терминологии:

• Swashbuckle — это проект с открытым исходным кодом для создания документов Swagger для веб-API, построенных с помощью ASP.NET Core MVC.
• Swagger — это машиночитаемое представление RESTful API, которое обеспечивает поддержку интерактивной документации, создание клиентских пакетов SDK и возможности обнаружения.

Данный учебный материал написан по примеру туториала «Создание первого веб-API с помощью ASP.NET Core MVC и Visual Studio». Если вам интересно, его можно скачать с GitHub.

Начало работы

Swashbuckle состоит из двух компонентов:

• Swashbuckle.SwaggerGen: содержит функции для создания документов JSON Swagger, которые описывают объекты, методы, типы возвращаемых значений и так далее.
• Swashbuckle.SwaggerUI: встроенная версия пользовательского интерфейса Swagger, который с помощью указанных выше документов создает индивидуально настраиваемый инструмент для описания функций веб-API и содержит функции тестирования для общедоступных методов.

Пакеты NuGet

Чтобы добавить Swashbuckle, можно воспользоваться одним из способов:

С помощью консоли диспетчера пакетов:

В Visual Studio:

o Правой кнопкой мыши щелкните проект в Обозревателе решений > Управление пакетами NuGet.
o Введите в поле поиска текст Swashbuckle.
o Поставьте флажок Include prerelease (Включить предварительный выпуск).
o В качестве источника пакетов укажите nuget.org.
o Коснитесь Swashbuckle package (пакет Swashbuckle), а затем — Install (Установить).

Добавьте Swagger и настройте его в связующее ПО

Добавьте SwaggerGen в набор сервисов в методах Configure и ConfigureServices, активируйте связующее ПО для обработки созданного документа JSON и пользовательского интерфейса Swagger.

В Visual Studio нажмите F5 для запуска приложения и перейдите к http://localhost: /swagger/v1/swagger.json . Здесь вы увидите созданный документ, описывающий конечные точки.

Примечание: браузеры Microsoft Edge, Google Chrome и Firefox отображают документы JSON без дополнительных настроек. Для Chrome созданы расширения, позволяющие форматировать документ для удобства чтения. Ниже приведен сокращенный пример на JavaScript.

Этот документ используется для работы пользовательского интерфейса Swagger, доступного по адресу: http://localhost: /swagger/ui .

Каждый метод в контроллере ToDo можно протестировать из пользовательского интерфейса. Коснитесь метода, чтобы развернуть раздел, добавьте необходимые параметры и нажмите «Try it out!» (Попробовать).

Настройка и расширяемость

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

Информация и описание API

Метод ConfigureSwaggerGen предназначен для добавления сведений об авторе и лицензии, а также описания.

На следующем рисунке показан пользовательский интерфейс Swagger с информацией о версии.

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

Чтобы включить комментарии XML, правой кнопкой мыши щелкните проект в Visual Studio и выберите Properties (Свойства). Затем поставьте флажок XML Documentation file (Файл документации XML) под разделом Output Settings (Настройки выхода).

Сконфигурируйте Swagger для использования созданного файла XML.

Примечание: для Linux и операционных систем, не принадлежащих к семейству Windows, имена файлов и каталогов чувствительны к регистру. Например, поиск файла с именем ToDoApi.XML возможен в Windows, но невозможен в CentOS.

В коде выше ApplicationBasePath получает путь к базовому каталогу приложения, что позволяет настроить полный путь к комментариям XML. TodoApi.xml работает только в этом примере, имя созданного файла XML с комментариями назначается на основе имени приложения.

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

Помните, что пользовательский интерфейс использует созданный файл JSON, и в нем также содержатся эти комментарии.

Для большей наглядности добавим , содержимое которого может представлять собой текст, объект JSON или XML для дальнейшего документирования метода.

Обратите внимание, как благодаря дополнительным комментариям улучшился пользовательский интерфейс.

DataAnnotations

В API можно добавить контроллер System.ComponentModel.DataAnnotations , чтобы улучшить элементы пользовательского интерфейса Swagger.

Добавление аннотации [Required] к свойству Name класса TodoItem меняет информацию ModelSchema в пользовательском интерфейсе. Агенты проверки [Produces(«application/json»)] , RegularExpression и другие функции служат для уточнения информации, отображаемой на создаваемой странице. Чем больше метаданных используется в коде, тем более информативной становится справочная страница пользовательского интерфейса или API.

Описание типов ответов

Разработчики, создающие высоконагруженные приложения, уделяют особое внимание выдаваемым результатам, особенно типам ответов, кодам ошибок (если они не стандартные). Для этого используются комментарии XML и DataAnnotations.

Для примера возьмем метод Create() . По умолчанию он выдает ответ «201 Created» (если элемент действительно создан) или «204 No Content» (если в тело POST не переданы данные). Однако не существует документации, которая подскажет, каким будет тот или иной ответ. Чтобы исправить ситуацию, добавим следующий фрагмент кода.

Настройка пользовательского интерфейса

Готовый пользовательский интерфейс — функциональный и удобный, но при создании страниц документации для API вы наверняка захотите использовать свой бренд или фирменный стиль.

Это можно сделать с помощью компонентов Swashbuckle. Вам нужно будет добавить ресурсы для обслуживания статических файлов, которые обычно не включаются в проект веб-API, а затем создать структуру папок для их размещения.

Добавьте к проекту пакет NuGet «Microsoft.AspNetCore.StaticFiles»: «1.0.0-*» .

Включите связующее ПО для статических файлов.

Возьмите файл index.html, который используется на странице пользовательского интерфейса Swagger, из репозитория Github _ и переместите его в папку wwwroot/swagger/ui , после чего создайте новый файл custom.css в той же папке.

Сделайте ссылку на custom.css в файле index.html.

В следующем CSS представлен образец индивидуально настроенного заголовка страницы.

Но это далеко не всё, что можно сделать со страницей. Весь перечень возможностей для пользовательского интерфейса смотрите на GitHub в репозитории Swagger UI.

Источник