Swagger ir bezmaksas atvērtā koda ietvars interaktīvas un lietotājam draudzīgas API dokumentācijas izveidei. Tas ģenerē interaktīvas tīmekļa lapas, kas ļauj pārbaudīt API ar dažādām ievadēm.
Swagger atbalsta gan JSON, gan XML lietderīgās slodzes. Tā ģenerētā dokumentācija ir piemērota lietošanai izstrādātājiem un tiem, kas nav izstrādātāji.
Varat dokumentēt savas NestJS tīmekļa API, izmantojot Swagger, izmantojot vienkāršus dekoratorus, neatstājot savu IDE.
1. darbība. API ģenerēšana
Pirms darba sākšanas jums ir jāizveido demonstrācijas API, lai Swagger ģenerētu savu dokumentāciju.
Demonstrācijas API tiks izveidota no jauna, izmantojot NestJS CLI.
Pirmkārt, ģenerējiet jaunu NestJS projektu, palaižot:
ligzda jauna <jūsu projekta nosaukums>
Pēc tam mainiet direktoriju uz savu jau izveidoto projektu, izpildot:
cd <jūsu projekta nosaukums>
Pēc tam ar CLI ģenerēsiet REST API, izpildot:
Nest ģenerēt resursu demonstrāciju --bez specifikācijas
Tiks parādīts vaicājums “Kādu transporta slāni jūs izmantojat?” izvēlieties REST API.
Tiks parādīts vēl viens vaicājums: "Vai vēlaties ģenerēt CRUD ieejas punktus?" Tips Y un sit Ievadiet.
Iepriekš minētā komanda ģenerē pilnībā funkcionējoša REST API ar CRUD galapunktiem un bez vienības pārbaudes failiem. Līdz ar to, --bez specifikācijas karodziņu augstāk esošajā komandā.
2. darbība. Instalējiet Swagger
Instalējiet Swagger un tā Express UI bibliotēku, palaižot:
npm uzstādīt--save @nestjs/swagger swagger-ui-express
3. darbība: konfigurējiet Swagger
Tavā galvenais.ts fails, imports SwaggerModule un DocumentBuilder no @nestjs/swagger.
DocumentBuilder palīdz strukturēt pamatdokumentu. Tas nodrošina vairākas metodes, kuras varat savienot kopā un aizvērt ar būvēt metodi.
Šīs metodes ļauj konfigurēt daudzus atribūtus, piemēram, nosaukumu, aprakstu un versiju.
Izveidot a konfigurācija objekta mainīgais jūsu bootstrap darbojas šādi:
konst konfigurācija = jauns DocumentBuilder()
.setTitle('Demonstrācijas API')
.setDescription('Demonstrācijas API ar CRUD funkcionalitāte")
.setVersion('1.0')
.būvēt();
Jauns DocumentBuilder gadījums izveido pamatdokumentu, kas atbilst OpenAPI specifikācija. Pēc tam varat izmantot šo gadījumu, lai iestatītu nosaukumu, aprakstu un versiju, izmantojot atbilstošās metodes.
Pēc tam jums būs jāizveido pilns dokuments ar visiem HTTP maršrutiem, kas definēti, izmantojot pamatdokumentu.
Lai to izdarītu, zvaniet uz izveidot dokumentu metode SwaggerModule. CreateDocument pieņem divus argumentus: lietojumprogrammas gadījumu un Swagger opciju objektu. Saglabājiet šī zvana rezultātu mainīgajā, lai to izmantotu vēlāk:
konstdokumentu = SwaggerModule.createDocument (lietotne, konfigurācija);
Tālāk zvaniet uz uzstādīt metode SwaggerModule. Iestatīšanas metode ietver trīs argumentus:
- Swagger lietotāja interfeisa ceļš. Pēc vienošanās jūs varat izmantot “api”.
- Lietojumprogrammas gadījums
- Pilns dokuments
Turklāt iestatīšanas metode izmanto izvēles opciju objektu. Skat NestJS dokumentācija par Swagger dokumentu opcijām lai uzzinātu vairāk par to.
Tā kā:
SwaggerModule.setup('api', lietotne, dokuments);
Sāciet savu pieteikumu un dodieties uz http://localhost:
Lapā vajadzētu redzēt Swagger lietotāja interfeisu.
Augšējais attēls ir Swagger lietotāja saskarnes noklusējuma skats ar visiem jūsu kontrollerī definētajiem HTTP maršrutiem. Jums tas būs jāpielāgo, lai tas atbilstu jūsu API funkcionalitātei.
4. darbība. Pielāgojiet API rekvizītus
Pēc noklusējuma Swagger prefiksu visu HTTP maršruta sadaļu ar virsrakstu, kas skan “noklusējums”. Varat to mainīt, atzīmējot kontroliera klasi ar @ApiTags dekorētājs un kā argumentu nododot vēlamo atzīmi.
Tā kā:
// demo.controller.ts
imports { ApiTags } no '@nestjs/swagger';
@ApiTags("Demo")
@Controller("demonstrācija")
eksportētklasē DemoController {
Sadaļā Shēmas ir ietverti jūsu API datu pārsūtīšanas objekti. Pašlaik lietotāja saskarnē nav iekļauts neviens no to īpašumiem.
Lai paziņotu to īpašības lietotāja saskarnē, vienkārši pievienojiet dekoratorus. Anotējiet katru nepieciešamo rekvizītu ar @ApiProperty dekorators. Anotējiet izvēles rekvizītus ar @ApiPropertyOptional dekorators.
Piemēram:
// create-demo.dto.ts
imports { ApiProperty, ApiPropertyOptional } no '@nestjs/swagger';
eksportētklasē CreateDemoDto {
@ApiProperty({
veids: Stīga,
apraksts: "Šis ir obligāts īpašums",
})
īpašums: virkne;
@ApiPropertyOptional({
veids: Stīga,
apraksts: "Šis ir neobligāts īpašums",
})
neobligāts īpašums: virkne;
}
@ApiProperty un @ApiPropertyOptional dekoratori katrs pieņem opciju objektu. Šis objekts apraksta tālāk norādīto īpašību.
Ņemiet vērā, ka opciju objekts izmanto JavaScript, nevis TypeScript. Līdz ar to JavaScript tipa deklarācijas (t.i., virkne, nevis virkne).
Anotējot datu pārsūtīšanas objekta rekvizītus, sadaļai Shēmas tiek pievienots paredzamo datu piemērs. Tas arī atjaunina saistīto HTTP maršrutu ar paredzamo datu piemēru.
5. darbība: iestatiet API atbildes
Kontroliera klasē izmantojiet @ApiResponse dekoratoriem, lai dokumentētu visas iespējamās atbildes katram HTTP maršrutam. Katram galapunktam dažādi @ApiResponse dekoratori apraksta gaidāmo atbilžu veidu.
Mēs esam paskaidrojuši izplatītas HTTP atbildes, ja jūs nezināt, ko tie nozīmē.
@ApiResponse dekoratori pieņem neobligātu objektu, kas apraksta atbildi.
Kopējās POST atbildes
POST pieprasījumam iespējamās atbildes ir šādas:
- ApiCreatedResponse, par veiksmīgu 201 izveidoto atbildi.
- ApiUnprocessableEnityResponse, par neveiksmīgām 422 neapstrādājamām entītiju atbildēm.
- ApiForbiddenResponse, par 403 aizliegtām atbildēm.
Piemēram:
// demo.controller.ts
@Post()
@ApiCreatedResponse({apraksts: 'Izveidots veiksmīgi' })
@ApiUnprocessableEntityResponse({apraksts: 'Bad Request' })
@ApiForbiddenResponse({apraksts: 'Neautorizēts pieprasījums' })
izveidot (@Ķermenis() createDemoDto: CreateDemoDto) {
atgrieztiesšis.demoService.create (createDemoDto);
}
Kopējās GET atbildes
Uz GET pieprasījumiem iespējamās atbildes ir šādas:
- ApiOkResponse, par 200 ok atbildēm.
- ApiForbiddenResponse, par 403 aizliegtām atbildēm.
- ApiNotFoundResponse, 404 neatrasta atbildēm.
Piemēram:
// demo.controller.ts
@Gūt()
@ApiOkResponse({apraksts: 'Resursi tika veiksmīgi atgriezti' })
@ApiForbiddenResponse({apraksts: 'Neautorizēts pieprasījums' })
atrast visu() {
atgrieztiesšis.demoService.findAll();
}
@Gūt(':id')
@ApiOkResponse({apraksts: 'Resurss tika veiksmīgi atgriezts' })
@ApiForbiddenResponse({apraksts: 'Neautorizēts pieprasījums' })
@ApiNotFoundResponse({apraksts: 'Resurss nav atrasts' })
atrast vienu (@Param('ES izdarīju: virkne) {
atgrieztiesšis.demoService.findOne(+id);
}
Kopējās atbildes uz ielāpu un ATJAUNINĀJUMU
Uz PATCH un UPDATE pieprasījumiem iespējamās atbildes ir šādas:
- ApiOkResponse, par 200 ok atbildēm.
- ApiNotFoundResponse, 404 neatrasta atbildēm.
- ApiUnprocessibleEntityResponse, par neveiksmīgām 422 neapstrādājamām entītiju atbildēm.
- ApiForbiddenResponse, par 403 aizliegtām atbildēm.
Piemēram:
// demo.controller.ts
@Patch(':id')
@ApiOkResponse({apraksts: 'Resurss tika veiksmīgi atjaunināts' })
@ApiNotFoundResponse({apraksts: 'Resurss nav atrasts' })
@ApiForbiddenResponse({apraksts: 'Neautorizēts pieprasījums' })
@ApiUnprocessableEntityResponse({apraksts: 'Bad Request' })
Atjaunināt(@Param('ES izdarīju: virkne, @Ķermenis() updateDemoDto: UpdateDemoDto) {
atgrieztiesšis.demoService.update(+id, updateDemoDto);
}
Izplatītas DELETE atbildes
Uz DELETE pieprasījumiem iespējamās atbildes ir šādas:
- ApiOkResponse, par 200 ok atbildēm.
- ApiForbiddenResponse, par 403 aizliegtām atbildēm.
- ApiNotFoundResponse, 404 neatrasta atbildēm.
Piemēram:
// demo.controller.ts
@Dzēst(':id')
@ApiOkResponse({apraksts: 'Resurss tika veiksmīgi atgriezts' })
@ApiForbiddenResponse({apraksts: 'Neautorizēts pieprasījums' })
@ApiNotFoundResponse({apraksts: 'Resurss nav atrasts' })
noņemt (@Param('ES izdarīju: virkne) {
atgrieztiesšis.demoService.remove(+id);
}
Šie dekoratori aizpilda jūsu dokumentāciju ar iespējamām atbildēm. Varat tos apskatīt, izmantojot nolaižamo izvēlni blakus katram maršrutam.
Jūsu dokumentācijas skatīšana
Kad iestatīšana ir pabeigta, varat skatīt savu dokumentāciju localhost:
Swagger API dokumentācijas pamatelementi ir apraksts, atbilžu veidi un shēmas definīcija. Šīs ir pamata lietas, kas nepieciešamas, lai izveidotu labu API dokumentāciju.
