Swagger е безплатна рамка с отворен код за създаване на интерактивна и удобна за потребителя API документация. Той генерира интерактивни уеб страници, които ви позволяват да тествате API с различни входове.
Swagger поддържа както JSON, така и XML полезни натоварвания. Документацията, която генерира, е подходяща за използване от разработчици и неразработчици.
Можете да документирате своите NestJS уеб API чрез Swagger, като използвате прости декоратори, без да се налага да напускате вашата IDE.
Стъпка 1: Генериране на API
Преди да започнете, трябва да създадете демонстрационен API, който Swagger ще генерира неговата документация.
Ще генерирате демо API от нулата, като използвате NestJS CLI.
Първо, генерирайте нов NestJS проект, като стартирате:
гнездо ново <име-на-вашия-проект>
След това променете директорията към вашия вече създаден проект, като изпълните:
cd <име-на-вашия-проект>
След това ще генерирате REST API с CLI, като изпълните:
nest генериране на ресурс демонстрация --не-спец
Ще видите запитване с въпроса „Какъв транспортен слой използвате?“ изберете REST API.
Ще видите друга заявка, която пита: „Искате ли да генерирате CRUD входни точки?“ Тип Y и удари Въведете.
Горната команда генерира напълно функционален REST API с крайни точки на CRUD и без файловете за модулен тест. Следователно, на --не-спец флаг в горната команда.
Стъпка 2: Инсталирайте Swagger
Инсталирайте Swagger и неговата Express UI библиотека, като стартирате:
npm Инсталирай--save @nestjs/swagger swagger-ui-express
Стъпка 3: Конфигурирайте Swagger
Във вашия main.ts файл, импортиране SwaggerModule и DocumentBuilder от @nestjs/swagger.
DocumentBuilder помага при структурирането на основен документ. Той предоставя няколко метода, които можете да свържете заедно и да затворите с изграждане метод.
Тези методи позволяват конфигурацията на много атрибути, като заглавие, описание и версия.
Създавам конфиг обектна променлива във вашия начално зареждане функционира така:
конст конфигурация = нов DocumentBuilder()
.setTitle('Demo API')
.setDescription('Демонстрационен API с CRUD функционалност')
.setVersion('1.0')
.build();
Нов екземпляр на DocumentBuilder създава основен документ, който съответства на Спецификация на OpenAPI. След това можете да използвате този екземпляр, за да зададете заглавието, описанието и версията чрез съответните им методи.
След това ще трябва да създадете пълен документ с всички HTTP маршрути, дефинирани с помощта на основния документ.
За да направите това, обадете се на createDocument метод на SwaggerModule. createDocument приема два аргумента: екземпляр на приложение и обект с опции на Swagger. Запазете резултата от това извикване в променлива за по-късна употреба:
констдокумент = SwaggerModule.createDocument (приложение, конфигурация);
След това се обадете на настройвам метод на SwaggerModule. Методът за настройка приема три аргумента:
- Пътят на потребителския интерфейс на Swagger. По конвенция можете да използвате „api“.
- Екземпляр на приложение
- Пълният документ
Освен това методът за настройка приема незадължителен обект с опции. Вижте Документация на NestJS относно опциите за документ Swagger за да научите повече за това.
Така:
SwaggerModule.setup('api', приложение, документ);
Стартирайте вашето приложение и отидете на http://localhost:
Трябва да видите потребителския интерфейс на Swagger, показан на страницата.
Изображението по-горе е изгледът по подразбиране на потребителския интерфейс на Swagger, с дефинирани всички HTTP маршрути във вашия контролер. Ще трябва да го персонализирате, за да отговаря на вашата функционалност на API.
Стъпка 4: Персонализиране на свойствата на API
По подразбиране Swagger префиксира цялата секция на HTTP маршрута със заглавие, което гласи „по подразбиране“. Можете да промените това, като анотирате вашия клас контролер с @ApiTags декоратор и предаване на предпочитания ви маркер като аргумент.
Така:
// demo.controller.ts
импортиране {ApiTags} от '@nestjs/swagger';
@ApiTags('Демонстрация')
@Контролер('демонстрация')
износклас DemoController {
Разделът Схеми съдържа обектите за прехвърляне на данни във вашия API. Понастоящем потребителският интерфейс не включва нито едно от техните свойства.
За да декларирате техните свойства в потребителския интерфейс, просто добавете декоратори. Анотирайте всяко необходимо свойство с @ApiProperty декоратор. Анотирайте незадължителни свойства с @ApiPropertyOptional декоратор.
Например:
// create-demo.dto.ts
импортиране {ApiProperty, ApiPropertyOptional} от '@nestjs/swagger';
износклас CreateDemoDto {
@ApiProperty({
Тип: низ,
описание: „Това е задължително свойство“,
})
Имот: низ;
@ApiPropertyOptional({
Тип: низ,
описание: „Това е незадължително свойство“,
})
optionalProperty: низ;
}
Всеки от декораторите @ApiProperty и @ApiPropertyOptional приема обект с опции. Този обект описва свойството, което следва по-долу.
Обърнете внимание, че обектът с опции използва JavaScript, а не TypeScript. Оттук и декларациите за тип на JavaScript (т.е. низ, а не низ).
Анотирането на свойствата на обекта за прехвърляне на данни добавя пример за очакваните данни към раздела Схеми. Той също така актуализира свързания HTTP маршрут с пример за очакваните данни.
Стъпка 5: Задаване на API отговори
Във вашия клас на контролер използвайте @ApiResponse декоратори за документиране на всички потенциални отговори за всеки HTTP маршрут. За всяка крайна точка различните декоратори на @ApiResponse описват вида на очакваните отговори.
Обяснихме общи HTTP отговори, в случай че не сте запознати със значението им.
Декораторите @ApiResponse приемат незадължителен обект, който описва отговора.
Често срещани POST отговори
За POST заявка вероятните отговори включват:
- ApiCreatedResponse, за успешни 201 създадени отговора.
- ApiUnprocessableEnityResponse, за неуспешни 422 необработими отговора на обекта.
- ApiForbiddenResponse, за 403 забранени отговора.
Например:
// demo.controller.ts
@Публикуване()
@ApiCreatedResponse({ описание: „Създадено успешно“ })
@ApiUnprocessableEntityResponse({ описание: 'Грешна заявка' })
@ApiForbiddenResponse({ описание: 'Неупълномощена заявка' })
създайте (@Тяло() createDemoDto: CreateDemoDto) {
връщанетова.demoService.create (createDemoDto);
}
Често срещани GET отговори
За GET заявки вероятните отговори включват:
- ApiOkResponse, за 200 ок отговора.
- ApiForbiddenResponse, за 403 забранени отговора.
- ApiNotFoundResponse, за 404 ненамерени отговора.
Например:
// demo.controller.ts
@Вземете()
@ApiOkResponse({ описание: „Ресурсите бяха върнати успешно“ })
@ApiForbiddenResponse({ описание: 'Неупълномощена заявка' })
findAll() {
връщанетова.demoService.findAll();
}
@Вземете(':документ за самоличност')
@ApiOkResponse({ описание: „Ресурсът беше върнат успешно“ })
@ApiForbiddenResponse({ описание: 'Неупълномощена заявка' })
@ApiNotFoundResponse({ описание: „Ресурсът не е намерен“ })
findOne(@Парам('направих: низ) {
връщанетова.demoService.findOne(+id);
}
Често срещани отговори PATCH и UPDATE
За заявки за КОРЕКЦИЯ и АКТУАЛИЗАЦИЯ вероятните отговори включват:
- ApiOkResponse, за 200 ок отговора.
- ApiNotFoundResponse, за 404 ненамерени отговора.
- ApiUnprocessibleEntityResponse, за неуспешни 422 необработими отговора на обекта.
- ApiForbiddenResponse, за 403 забранени отговора.
Например:
// demo.controller.ts
@Кръпка(':документ за самоличност')
@ApiOkResponse({ описание: „Ресурсът беше актуализиран успешно“ })
@ApiNotFoundResponse({ описание: „Ресурсът не е намерен“ })
@ApiForbiddenResponse({ описание: 'Неупълномощена заявка' })
@ApiUnprocessableEntityResponse({ описание: 'Грешна заявка' })
актуализация(@Парам('направих: низ, @Тяло() updateDemoDto: UpdateDemoDto) {
връщанетова.demoService.update(+id, updateDemoDto);
}
Често срещани отговори ИЗТРИВАНЕ
За заявките за ИЗТРИВАНЕ вероятните отговори включват:
- ApiOkResponse, за 200 ок отговора.
- ApiForbiddenResponse, за 403 забранени отговора.
- ApiNotFoundResponse, за 404 ненамерени отговора.
Например:
// demo.controller.ts
@Изтрий(':документ за самоличност')
@ApiOkResponse({ описание: „Ресурсът беше върнат успешно“ })
@ApiForbiddenResponse({ описание: 'Неупълномощена заявка' })
@ApiNotFoundResponse({ описание: „Ресурсът не е намерен“ })
Премахване(@Парам('направих: низ) {
връщанетова.demoService.remove(+id);
}
Тези декоратори попълват вашата документация с възможни отговори. Можете да ги видите, като използвате падащото меню до всеки маршрут.
Преглед на вашата документация
Когато настройката приключи, можете да прегледате документацията си на локален хост:
Най-важното в документацията на Swagger API са описанието, типовете отговори и дефиницията на схемата. Това са основните неща, необходими за създаване на добра API документация.