Swagger — это бесплатная платформа с открытым исходным кодом для создания интерактивной и удобной документации по API. Он генерирует интерактивные веб-страницы, которые позволяют тестировать API с различными входными данными.

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

Вы можете документировать свои веб-API NestJS через Swagger, используя простые декораторы, не выходя из IDE.

Шаг 1. Генерация API

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

Вы создадите демонстрационный API с нуля, используя интерфейс командной строки NestJS.

Во-первых, создайте новый проект NestJS, запустив:

гнездо новое <название вашего проекта>

Затем измените каталог на уже созданный проект, запустив:

CD <название вашего проекта>

Далее вы сгенерируете REST API с помощью CLI, выполнив:

демонстрация ресурсов генерирования гнезда --no-spec

Вы увидите запрос «Какой транспортный уровень вы используете?» Выбрать РЕСТ API.

instagram viewer

Вы увидите еще один запрос: «Хотите ли вы сгенерировать точки входа CRUD?» Тип Д и ударил Войти.

Команда выше генерирует полнофункциональный REST API с конечными точками CRUD и без файлов модульных тестов. Следовательно --no-spec флаг в команде выше.

Шаг 2: Установите Swagger

Установите Swagger и его библиотеку пользовательского интерфейса Express, выполнив:

нпм установить--save @nestjs/swagger swagger-ui-express

Шаг 3: Настройте Swagger

В твоей main.ts файл, импорт SwaggerModule а также DocumentBuilder из @nestjs/чванство.

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

Эти методы позволяют настраивать многие атрибуты, такие как заголовок, описание и версия.

Создать конфигурация объектная переменная в вашем начальная загрузка функционировать так:

константа конфигурация = новый DocumentBuilder()
 .setTitle('Демонстрационный API')
 .setDescription('Демонстрационный API с функциональность CRUD')
 .setVersion('1.0')
 .строить();

Новый экземпляр DocumentBuilder создает базовый документ, соответствующий Спецификация OpenAPI. Затем вы можете использовать этот экземпляр для установки заголовка, описания и версии с помощью соответствующих методов.

Далее вам нужно создать полный документ со всеми маршрутами HTTP, определенными с помощью базового документа.

Для этого позвоните в создать документ метод на SwaggerModule. createDocument принимает два аргумента: экземпляр приложения и объект параметров Swagger. Сохраните результат этого вызова в переменной для последующего использования:

константадокумент = SwaggerModule.createDocument (приложение, конфигурация);

Далее позвоните в настраивать метод на SwaggerModule. Метод setup принимает три аргумента:

  1. Путь пользовательского интерфейса Swagger. По соглашению вы можете использовать «api».
  2. Экземпляр приложения
  3. Полный документ

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

Вот так:

SwaggerModule.setup('API', приложение, документ);

Запустите приложение и перейдите к http://localhost:/api

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

Изображение выше — это представление пользовательского интерфейса Swagger по умолчанию со всеми определенными маршрутами HTTP в вашем контроллере. Вам нужно будет настроить его в соответствии с функциональностью вашего API.

Шаг 4. Настройте свойства API

По умолчанию Swagger добавляет префикс ко всему разделу HTTP-маршрута с заголовком «по умолчанию». Вы можете изменить это, аннотировав свой класс контроллера с помощью @ApiTags декоратор и передавая предпочитаемый тег в качестве аргумента.

Вот так:

// demo.controller.ts
импорт {Апитеги} из '@nestjs/swagger';
@ApiTags(«Демо»)
@контроллер(«демо»)
экспортучебный класс ДемоКонтроллер {

Раздел «Схемы» содержит объекты передачи данных в вашем API. В настоящее время пользовательский интерфейс не включает ни одно из их свойств.

Чтобы объявить их свойства в пользовательском интерфейсе, просто добавьте декораторы. Аннотируйте каждое необходимое свойство с помощью @АпиПроперти декоратор. Аннотируйте необязательные свойства с помощью @ApiPropertyOptional декоратор.

Например:

// создать-demo.dto.ts
импорт {Апипроперти, апипропертифакультативно} из '@nestjs/swagger';
экспортучебный класс CreateDemoDto {
@АпиПроперти({
тип: Нить,
 description: 'Это обязательное свойство',
 })
 имущество: нить;
@ApiPropertyOptional({
тип: Нить,
 description: 'Это необязательное свойство',
 })
 необязательное свойство: нить;
}

Каждый из декораторов @ApiProperty и @ApiPropertyOptional принимает объект параметров. Этот объект описывает свойство, которое следует ниже.

Обратите внимание, что объект параметров использует JavaScript, а не TypeScript. Отсюда и объявления типа JavaScript (т.е. String, а не string).

Аннотирование свойств объекта передачи данных добавляет пример ожидаемых данных в раздел «Схемы». Он также обновляет связанный маршрут HTTP с примером ожидаемых данных.

Шаг 5. Установите ответы API

В вашем классе контроллера используйте @Апиответ декораторы для документирования всех потенциальных ответов для каждого маршрута HTTP. Для каждой конечной точки разные декораторы @ApiResponse описывают тип ожидаемых ответов.

мы объяснили общие HTTP-ответы, если вы не знаете, что они означают.

Декораторы @ApiResponse принимают необязательный объект, описывающий ответ.

Общие ответы POST

Для запроса POST вероятные ответы включают:

  • Апикреатедреспонс, для успешных 201 созданных ответов.
  • Апиунпроцессаблеэнитиреспонсе, для ошибочных ответов 422 необрабатываемых объектов.
  • апифорбидденреспонс, для 403 запрещенных ответов.

Например:

// demo.controller.ts
@Почта()
@ApiCreatedResponse({ описание: «Успешно создано» })
@ApiUnprocessableEntityResponse({ описание: "Неверный запрос" })
@ApiForbiddenResponse({ описание: «Несанкционированный запрос» })
 Создайте(@Тело() createDemoDto: CreateDemoDto) {
возвращатьсяэто.demoService.create(createDemoDto);
 }

Общие ответы GET

Для запросов GET вероятные ответы включают:

  • АпиОкответ, за 200 хороших ответов.
  • апифорбидденреспонс, для 403 запрещенных ответов.
  • Апинотфаундреспонс, для 404 не найденных ответов.

Например:

// demo.controller.ts
@Получить()
@ApiOkResponse({ описание: "Ресурсы успешно возвращены" })
@ApiForbiddenResponse({ описание: «Несанкционированный запрос» })
 найти все() {
возвращатьсяэто.demoService.findAll();
 }
@Получить(':я бы')
@ApiOkResponse({ описание: "Ресурс успешно возвращен" })
@ApiForbiddenResponse({ описание: «Несанкционированный запрос» })
@ApiNotFoundResponse({ описание: «Ресурс не найден» })
 найтиодин(@Парам('я сделал: нить) {
возвращатьсяэто.demoService.findOne(+id);
 }

Распространенные ответы PATCH и UPDATE

Для запросов PATCH и UPDATE вероятные ответы включают:

  • АпиОкответ, за 200 хороших ответов.
  • Апинотфаундреспонс, для 404 не найденных ответов.
  • Апиунпроцессиблеэнтититреспонс, для ошибочных ответов 422 необрабатываемых объектов.
  • апифорбидденреспонс, для 403 запрещенных ответов.

Например:

// demo.controller.ts
@Пластырь(':я бы')
@ApiOkResponse({ описание: «Ресурс успешно обновлен» })
@ApiNotFoundResponse({ описание: «Ресурс не найден» })
@ApiForbiddenResponse({ описание: «Несанкционированный запрос» })
@ApiUnprocessableEntityResponse({ описание: "Неверный запрос" })
 Обновить(@Парам('я сделал: нить, @Тело() updateDemoDto: UpdateDemoDto) {
возвращатьсяэто.demoService.update(+id, updateDemoDto);
 }

Распространенные ответы DELETE

Для запросов DELETE вероятные ответы включают:

  • АпиОкответ, за 200 хороших ответов.
  • апифорбидденреспонс, для 403 запрещенных ответов.
  • Апинотфаундреспонс, для 404 не найденных ответов.

Например:

// demo.controller.ts
@Удалить(':я бы')
@ApiOkResponse({ описание: "Ресурс успешно возвращен" })
@ApiForbiddenResponse({ описание: «Несанкционированный запрос» })
@ApiNotFoundResponse({ описание: «Ресурс не найден» })
 удалять(@Парам('я сделал: нить) {
возвращатьсяэто.demoService.remove(+id);
 }

Эти декораторы заполняют вашу документацию возможными ответами. Вы можете просмотреть их, используя раскрывающийся список рядом с каждым маршрутом.

Просмотр вашей документации

После завершения настройки вы можете просмотреть документацию на локальный хост:/api. Он должен открыть вашу интерактивную документацию по API.

Основами документации Swagger API являются описание, типы ответов и определение схемы. Это основные вещи, необходимые для создания хорошей документации по API.