Swagger er et gratis rammeverk med åpen kildekode for å lage interaktiv og brukervennlig API-dokumentasjon. Den genererer interaktive nettsider som lar deg teste et API med ulike innganger.
Swagger støtter både JSON- og XML-nyttelast. Dokumentasjonen den genererer er egnet for utviklere og ikke-utviklere å bruke.
Du kan dokumentere NestJS-nett-API-ene dine via Swagger ved hjelp av enkle dekoratorer, uten å måtte forlate IDE-en din.
Trinn 1: Generering av API
Før du starter, må du lage et demo-API som Swagger vil generere dokumentasjonen.
Du vil generere demo-API fra bunnen av ved hjelp av NestJS CLI.
Generer først et nytt NestJS-prosjekt ved å kjøre:
reir ny <navn-på-prosjektet ditt>
Deretter endrer du katalogen til det allerede opprettede prosjektet ved å kjøre:
cd <navn-på-prosjektet ditt>
Deretter genererer du et REST API med CLI ved å kjøre:
nest generer ressursdemo --ingen spesifikasjon
Du vil se et søk som spør: "Hvilket transportlag bruker du?" å velge REST API.
Du vil se et annet søk som spør: "Vil du generere CRUD-inngangspunkter?" Type Y og treffer Tast inn.
Kommandoen ovenfor genererer en fullt funksjonell REST API med CRUD-endepunkter og uten enhetstestfilene. Derav --ingen spesifikasjon flagg i kommandoen ovenfor.
Trinn 2: Installer Swagger
Installer Swagger og dets Express UI-bibliotek ved å kjøre:
npm installere--lagre @nestjs/swagger swagger-ui-express
Trinn 3: Konfigurer Swagger
I din main.ts fil, import SwaggerModule og DocumentBuilder fra @nestjs/swagger.
DocumentBuilder hjelper til med å strukturere et basisdokument. Det gir flere metoder som du kan lenke sammen og lukke med bygge metode.
Disse metodene muliggjør konfigurasjon av mange attributter, for eksempel tittel, beskrivelse og versjon.
Lage en konfig objektvariabel i din Støvelhempe fungerer slik:
konst config = ny DocumentBuilder()
.setTitle('Demo API')
.setDescription('A Demo API med CRUD-funksjonalitet')
.setVersion('1.0')
.bygge();
En ny forekomst av DocumentBuilder oppretter et basisdokument som samsvarer med OpenAPI-spesifikasjon. Du kan deretter bruke denne forekomsten til å angi tittel, beskrivelse og versjon via deres passende metoder.
Deretter må du opprette et komplett dokument med alle HTTP-rutene definert ved hjelp av basisdokumentet.
For å gjøre dette, ring opprette Dokument metode på SwaggerModule. createDocument godtar to argumenter: en applikasjonsforekomst og et Swagger-alternativobjekt. Lagre resultatet av dette kallet i en variabel for senere bruk:
konstdokument = SwaggerModule.createDocument (app, config);
Deretter ringer du oppsett metode på SwaggerModule. Oppsettmetoden tar inn tre argumenter:
- Swagger UI-banen. Etter konvensjon kan du bruke "api".
- En applikasjonsforekomst
- Hele dokumentet
I tillegg tar oppsettsmetoden et valgfritt alternativobjekt. Se NestJS sin dokumentasjon om Swagger-dokumentalternativer for å lære mer om det.
Som så:
SwaggerModule.setup('api', app, dokument);
Start søknaden din og gå til http://localhost:
Du bør se Swagger UI vist på siden.
Bildet ovenfor er standardvisningen av Swagger-grensesnittet, med alle HTTP-rutene i kontrolleren definert. Du må tilpasse den for å passe API-funksjonaliteten din.
Trinn 4: Tilpass API-egenskaper
Som standard prefikser Swagger hele HTTP-ruteseksjonen med en overskrift som leser "standard." Du kan endre dette ved å kommentere kontrollerklassen din med @ApiTags dekoratør og sende din foretrukne tag som argument.
Som så:
// demo.controller.ts
import { ApiTags } fra '@nestjs/swagger';
@ApiTags('Demo')
@Kontroller('demo')
eksportklasse DemoController {
Skjema-delen inneholder dataoverføringsobjektene i API-en din. For øyeblikket inkluderer brukergrensesnittet ingen av egenskapene deres.
For å deklarere egenskapene deres i brukergrensesnittet, legg til dekoratører. Merk hver påkrevde egenskap med @ApiProperty dekoratør. Merk valgfrie egenskaper med @ApiPropertyOptional dekoratør.
For eksempel:
// create-demo.dto.ts
import { ApiProperty, ApiPropertyOptional } fra '@nestjs/swagger';
eksportklasse CreateDemoDto {
@ApiProperty({
type: String,
description: 'Dette er en nødvendig egenskap',
})
eiendom: streng;
@ApiPropertyOptional({
type: String,
description: 'Dette er en valgfri egenskap',
})
valgfri egenskap: streng;
}
@ApiProperty- og @ApiPropertyOptional-dekoratørene godtar hver et alternativobjekt. Det objektet beskriver egenskapen som følger nedenfor.
Merk at options-objektet bruker JavaScript, ikke TypeScript. Derav JavaScript-typeerklæringene (dvs. streng, ikke streng).
Ved å kommentere dataoverføringsobjektets egenskaper legges et eksempel på de forventede dataene til Skjema-delen. Den oppdaterer også den tilknyttede HTTP-ruten med et eksempel på de forventede dataene.
Trinn 5: Angi API-svar
I kontrollerklassen din bruker du @ApiResponse dekoratører for å dokumentere alle potensielle svar for hver HTTP-rute. For hvert endepunkt beskriver de forskjellige @ApiResponse-dekoratørene hva slags svar du kan forvente.
Vi har forklart vanlige HTTP-svar, i tilfelle du ikke er kjent med hva de betyr.
@ApiResponse-dekoratørene godtar et valgfritt objekt som beskriver svaret.
Vanlige POST-svar
For en POST-forespørsel inkluderer de sannsynlige svarene:
- ApiCreatedResponse, for vellykkede 201 opprettede svar.
- ApiUnprocessableEnityResponse, for mislykkede 422 ubearbeidbare enhetssvar.
- ApiForbiddenResponse, for 403 forbudte svar.
For eksempel:
// demo.controller.ts
@Post()
@ApiCreatedResponse({ beskrivelse: 'Opprettet med suksess' })
@ApiUnprocessableEntityResponse({ beskrivelse: 'Dårlig forespørsel' })
@ApiForbiddenResponse({ beskrivelse: 'Uautorisert forespørsel' })
skape(@Kropp() createDemoDto: CreateDemoDto) {
komme tilbakedette.demoService.create (createDemoDto);
}
Vanlige GET-svar
For GET-forespørsler inkluderer de sannsynlige svarene:
- ApiOkResponse, for 200 ok svar.
- ApiForbiddenResponse, for 403 forbudte svar.
- ApiNotFoundResponse, for 404 svar som ikke ble funnet.
For eksempel:
// demo.controller.ts
@Få()
@ApiOkResponse({ beskrivelse: 'Ressursene ble returnert' })
@ApiForbiddenResponse({ beskrivelse: 'Uautorisert forespørsel' })
findAll() {
komme tilbakedette.demoService.findAll();
}
@Få(':id')
@ApiOkResponse({ beskrivelse: 'Ressursen ble returnert' })
@ApiForbiddenResponse({ beskrivelse: 'Uautorisert forespørsel' })
@ApiNotFoundResponse({ beskrivelse: 'Ressurs ikke funnet' })
Finn én(@Param('jeg gjorde: streng) {
komme tilbakedette.demoService.findOne(+id);
}
Vanlige PATCH- og UPDATE-svar
For PATCH- og UPDATE-forespørsler inkluderer de sannsynlige svarene:
- ApiOkResponse, for 200 ok svar.
- ApiNotFoundResponse, for 404 svar som ikke ble funnet.
- ApiUnprocessibleEntityResponse, for mislykkede 422 ubearbeidbare enhetssvar.
- ApiForbiddenResponse, for 403 forbudte svar.
For eksempel:
// demo.controller.ts
@Lapp(':id')
@ApiOkResponse({ beskrivelse: 'Ressursen ble oppdatert' })
@ApiNotFoundResponse({ beskrivelse: 'Ressurs ikke funnet' })
@ApiForbiddenResponse({ beskrivelse: 'Uautorisert forespørsel' })
@ApiUnprocessableEntityResponse({ beskrivelse: 'Dårlig forespørsel' })
Oppdater(@Param('jeg gjorde: streng, @Kropp() updateDemoDto: UpdateDemoDto) {
komme tilbakedette.demoService.update(+id, updateDemoDto);
}
Vanlige SLETTE-svar
For SLETT-forespørsler inkluderer de sannsynlige svarene:
- ApiOkResponse, for 200 ok svar.
- ApiForbiddenResponse, for 403 forbudte svar.
- ApiNotFoundResponse, for 404 svar som ikke ble funnet.
For eksempel:
// demo.controller.ts
@Slett(':id')
@ApiOkResponse({ beskrivelse: 'Ressursen ble returnert' })
@ApiForbiddenResponse({ beskrivelse: 'Uautorisert forespørsel' })
@ApiNotFoundResponse({ beskrivelse: 'Ressurs ikke funnet' })
fjerne(@Param('jeg gjorde: streng) {
komme tilbakedette.demoService.remove(+id);
}
Disse dekoratørene fyller dokumentasjonen din med mulige svar. Du kan se dem ved å bruke rullegardinmenyen ved siden av hver rute.
Vise dokumentasjonen din
Når oppsettet er fullført, kan du se dokumentasjonen på lokal vert:
Det vesentlige av Swagger API-dokumentasjon er beskrivelsen, svartypene og skjemadefinisjonen. Dette er de grunnleggende tingene som trengs for å lage god API-dokumentasjon.
