Documentarea API-urilor NestJS cu Swagger

Swagger este un cadru gratuit, open-source, pentru crearea de documentație API interactivă și ușor de utilizat. Acesta generează pagini web interactive care vă permit să testați un API cu diverse intrări.

Swagger acceptă atât încărcături utile JSON, cât și XML. Documentația pe care o generează este potrivită pentru utilizare de către dezvoltatori și non-dezvoltatori.

Vă puteți documenta API-urile web NestJS prin Swagger folosind decoratori simpli, fără a fi nevoie să părăsiți IDE-ul dvs.

Pasul 1: Generarea API-ului

Înainte de a începe, trebuie să creați un API demonstrativ pe care Swagger îl va genera documentația.

Veți genera API-ul demo de la zero folosind CLI-ul NestJS.

În primul rând, generați un nou proiect NestJS rulând:

cuib nou <numele-proiectului dumneavoastră>

Apoi, schimbați directorul în proiectul dvs. deja creat executând:

CD <numele-proiectului dumneavoastră>

În continuare, veți genera un API REST cu CLI rulând:

nest generate demo de resurse --fără-spec

Veți vedea o interogare care vă întreabă „Ce strat de transport folosiți?” Selectați API-ul REST.

Veți vedea o altă interogare care vă întreabă „Doriți să generați puncte de intrare CRUD?” Tip Y și lovit introduce.

Comanda de mai sus generează un API REST complet funcțional cu puncte finale CRUD și fără fișierele de test unitar. Prin urmare, cel --fără-spec flag în comanda de mai sus.

Pasul 2: Instalați Swagger

Instalați Swagger și biblioteca sa Express UI rulând:

npm instalare--save @nestjs/swagger swagger-ui-express

Pasul 3: Configurați Swagger

În dumneavoastră principale.ts fișier, import SwaggerModule și DocumentBuilder din @nestjs/swagger.

DocumentBuilder ajută la structurarea unui document de bază. Acesta oferă mai multe metode pe care le puteți înlănțui și închide cu construi metodă.

Aceste metode permit configurarea multor atribute, cum ar fi titlul, descrierea și versiunea.

Creeaza o config variabilă obiect în dvs bootstrap functioneaza astfel:

const config = nou DocumentBuilder()
 .setTitle('Demo API')
 .setDescription('A Demo API cu funcționalitatea CRUD’)
 .setVersion('1.0')
 .construi();

O nouă instanță a DocumentBuilder creează un document de bază care se potrivește cu Specificația OpenAPI. Puteți utiliza apoi această instanță pentru a seta titlul, descrierea și versiunea prin metodele corespunzătoare.

În continuare, va trebui să creați un document complet cu toate rutele HTTP definite folosind documentul de bază.

Pentru a face acest lucru, sunați la createDocument metoda pe SwaggerModule. createDocument acceptă două argumente: o instanță de aplicație și un obiect de opțiuni Swagger. Stocați rezultatul acestui apel într-o variabilă pentru utilizare ulterioară:

constdocument = SwaggerModule.createDocument (aplicație, config);

Apoi, sunați la înființat metoda pe SwaggerModule. Metoda de configurare are trei argumente:

1. Calea Swagger UI. Prin convenție, puteți folosi „api”.
2. O instanță de aplicație
3. Documentul integral

În plus, metoda de configurare preia un obiect opțional opțional. Vedea Documentația NestJS privind opțiunile de documente Swagger pentru a afla mai multe despre el.

Ca astfel:

SwaggerModule.setup('api', aplicație, document);

Porniți aplicația și accesați http://localhost:/api

Ar trebui să vedeți interfața de utilizare Swagger afișată pe pagină.

Imaginea de mai sus este vizualizarea implicită a interfeței de utilizare Swagger, cu toate rutele HTTP din controlerul dvs. definite. Va trebui să-l personalizați pentru a se potrivi cu funcționalitatea dvs. API.

Pasul 4: Personalizați proprietățile API

În mod implicit, Swagger prefixează întreaga secțiune a rutei HTTP cu un titlu care scrie „implicit”. Puteți schimba acest lucru prin adnotarea clasei controlerului cu @ApiTags decorator și trecând eticheta preferată ca argument.

Ca astfel:

// demo.controller.ts
import { ApiTags } din '@nestjs/swagger';
@ApiTags("Demo")
@Controlor('demo')
exportclasă DemoController {

Secțiunea Scheme conține obiectele de transfer de date din API-ul dvs. În prezent, interfața de utilizare nu include niciuna dintre proprietățile lor.

Pentru a-și declara proprietățile în UI, pur și simplu adăugați decoratori. Adnotați fiecare proprietate necesară cu @ApiProperty decorator. Adnotați proprietățile opționale cu @ApiPropertyOptional decorator.

De exemplu:

// create-demo.dto.ts
import { ApiProperty, ApiPropertyOptional } din '@nestjs/swagger';
exportclasă CreateDemoDto {
@ApiProperty({
tip: Şir,
 descriere: „Aceasta este o proprietate obligatorie”,
 })
 proprietate: şir;
@ApiPropertyOptional({
tip: Şir,
 descriere: „Aceasta este o proprietate opțională”,
 })
 optionalProperty: şir;
}

Decoratorii @ApiProperty și @ApiPropertyOptional acceptă fiecare un obiect de opțiuni. Acest obiect descrie proprietatea care urmează mai jos.

Rețineți că obiectul opțiuni folosește JavaScript, nu TypeScript. De aici declarațiile de tip JavaScript (adică șir, nu șir).

Adnotarea proprietăților obiectului de transfer de date adaugă un exemplu de date așteptate la secțiunea Scheme. De asemenea, actualizează ruta HTTP asociată cu un exemplu de date așteptate.

Pasul 5: Setați răspunsurile API

În clasa dvs. de controler, utilizați @ApiResponse decoratorii să documenteze toate răspunsurile potențiale pentru fiecare rută HTTP. Pentru fiecare punct final, diferiții decoratori @ApiResponse descriu tipul de răspunsuri la care se așteaptă.

Am explicat răspunsuri HTTP comune, în cazul în care nu știți ce înseamnă ele.

Decoratorii @ApiResponse acceptă un obiect opțional care descrie răspunsul.

Răspunsuri POST comune

Pentru o solicitare POST, răspunsurile probabile includ:

• ApiCreatedResponse, pentru succes 201 de răspunsuri create.
• ApiUnprocessableEnityResponse, pentru 422 de răspunsuri neprocesabile ale entităților eșuate.
• ApiForbiddenResponse, pentru 403 răspunsuri interzise.

De exemplu:

// demo.controller.ts
@Post()
@ApiCreatedResponse({ descriere: „Creat cu succes” })
@ApiUnprocessableEntityResponse({ descriere: „Solicitare greșită”})
@ApiForbiddenResponse({ descriere: „Solicitare neautorizată” })
 crea(@Corp() createDemoDto: CreateDemoDto) {
întoarcereacest.demoService.create (createDemoDto);
 }

Răspunsuri GET comune

Pentru solicitările GET, răspunsurile probabile includ:

• ApiOkResponse, pentru 200 de răspunsuri ok.
• ApiForbiddenResponse, pentru 403 răspunsuri interzise.
• ApiNotFoundResponse, pentru 404 răspunsuri negăsite.

De exemplu:

// demo.controller.ts
@Obține()
@ApiOkResponse({ descriere: „Resursele au fost returnate cu succes” })
@ApiForbiddenResponse({ descriere: „Solicitare neautorizată” })
 Găsiți toate() {
întoarcereacest.demoService.findAll();
 }
@Obține(':id')
@ApiOkResponse({ descriere: „Resursa a fost returnată cu succes” })
@ApiForbiddenResponse({ descriere: „Solicitare neautorizată” })
@ApiNotFoundResponse({ descriere: „Resursa nu a fost găsită” })
 găsește una(@Param('am facut: şir) {
întoarcereacest.demoService.findOne(+id);
 }

Răspunsuri comune PATCH și UPDATE

Pentru solicitările PATCH și UPDATE, răspunsurile probabile includ:

• ApiOkResponse, pentru 200 de răspunsuri ok.
• ApiNotFoundResponse, pentru 404 răspunsuri negăsite.
• ApiUnprocessibleEntityResponse, pentru 422 de răspunsuri neprocesabile ale entităților eșuate.
• ApiForbiddenResponse, pentru 403 răspunsuri interzise.

De exemplu:

// demo.controller.ts
@Plasture(':id')
@ApiOkResponse({ descriere: „Resursa a fost actualizată cu succes” })
@ApiNotFoundResponse({ descriere: „Resursa nu a fost găsită” })
@ApiForbiddenResponse({ descriere: „Solicitare neautorizată” })
@ApiUnprocessableEntityResponse({ descriere: „Solicitare greșită”})
 Actualizați(@Param('am facut: şir, @Corp() updateDemoDto: UpdateDemoDto) {
întoarcereacest.demoService.update(+id, updateDemoDto);
 }

Răspunsuri comune DELETE

Pentru cererile DELETE, răspunsurile probabile includ:

• ApiOkResponse, pentru 200 de răspunsuri ok.
• ApiForbiddenResponse, pentru 403 răspunsuri interzise.
• ApiNotFoundResponse, pentru 404 răspunsuri negăsite.

De exemplu:

// demo.controller.ts
@Șterge(':id')
@ApiOkResponse({ descriere: „Resursa a fost returnată cu succes” })
@ApiForbiddenResponse({ descriere: „Solicitare neautorizată” })
@ApiNotFoundResponse({ descriere: „Resursa nu a fost găsită” })
 elimina(@Param('am facut: şir) {
întoarcereacest.demoService.remove(+id);
 }

Acești decoratori completează documentația dvs. cu posibile răspunsuri. Le puteți vizualiza folosind meniul derulant de lângă fiecare rută.

Vizualizarea documentației dvs

Când configurarea este completă, puteți vizualiza documentația pe gazdă locală:/api. Ar trebui să afișeze documentația interactivă API.

Elementele esențiale ale documentației Swagger API sunt descrierea, tipurile de răspuns și definiția schemei. Acestea sunt lucrurile de bază necesare pentru a crea o documentație API bună.