Swagger er en gratis open source-ramme til at skabe interaktiv og brugervenlig API-dokumentation. Det genererer interaktive websider, der giver dig mulighed for at teste en API med forskellige input.
Swagger understøtter både JSON- og XML-nyttelast. Den dokumentation, den genererer, er velegnet til at bruge udviklere og ikke-udviklere.
Du kan dokumentere dine NestJS web-API'er via Swagger ved hjælp af simple dekoratorer uden at skulle forlade din IDE.
Trin 1: Generering af API
Før du starter, skal du oprette en demo-API, som Swagger vil generere sin dokumentation.
Du vil generere demo-API'en fra bunden ved hjælp af NestJS CLI.
Generer først et nyt NestJS-projekt ved at køre:
rede ny <navn-på-dit-projekt>
Skift derefter mappen til dit allerede oprettede projekt ved at køre:
cd <navn-på-dit-projekt>
Dernæst genererer du en REST API med CLI ved at køre:
nest generer ressourcedemo -- ingen spec
Du vil se en forespørgsel, der spørger: "Hvilket transportlag bruger du?" Vælg REST API.
Du vil se en anden forespørgsel, der spørger: "Vil du generere CRUD-indgangspunkter?" Type Y og ramte Gå ind.
Kommandoen ovenfor genererer en fuldt funktionel REST API med CRUD-endepunkter og uden enhedstestfilerne. Derfor er -- ingen spec flag i kommandoen ovenfor.
Trin 2: Installer Swagger
Installer Swagger og dets Express UI-bibliotek ved at køre:
npm installere--gem @nestjs/swagger swagger-ui-express
Trin 3: Konfigurer Swagger
I din main.ts fil, import Swaggermodul og DocumentBuilder fra @nestjs/swagger.
DocumentBuilder hjælper med at strukturere et basisdokument. Det giver flere metoder, som du kan kæde sammen og lukke med bygge metode.
Disse metoder muliggør konfiguration af mange attributter, såsom titel, beskrivelse og version.
Lave en config objektvariabel i din bootstrap fungerer sådan:
konst config = ny DocumentBuilder()
.setTitle('Demo API')
.setDescription('A Demo API med CRUD-funktionalitet')
.setVersion('1.0')
.build();
En ny forekomst af DocumentBuilder opretter et basisdokument, der matcher OpenAPI-specifikation. Du kan derefter bruge denne instans til at indstille titlen, beskrivelsen og versionen via deres passende metoder.
Dernæst skal du oprette et komplet dokument med alle HTTP-ruterne defineret ved hjælp af basisdokumentet.
For at gøre dette skal du ringe til oprette Dokument metode på SwaggerModule. createDocument accepterer to argumenter: en applikationsforekomst og et Swagger-optionsobjekt. Gem resultatet af dette opkald i en variabel til senere brug:
konstdokument = SwaggerModule.createDocument (app, config);
Ring derefter til Opsætning metode på SwaggerModule. Opsætningsmetoden bruger tre argumenter:
- Swagger UI-stien. Efter konvention kan du bruge "api".
- En applikationsinstans
- Det fulde dokument
Derudover tager opsætningsmetoden et valgfrit indstillingsobjekt. Se NestJS's dokumentation om Swagger-dokumentmuligheder at lære mere om det.
Ligesom:
SwaggerModule.setup('api', app, dokument);
Start din ansøgning og gå til http://localhost:
Du bør se Swagger UI vist på siden.
Billedet ovenfor er standardvisningen af Swagger UI, med alle HTTP-ruterne i din controller defineret. Du bliver nødt til at tilpasse den, så den passer til din API-funktionalitet.
Trin 4: Tilpas API-egenskaber
Som standard præfikser Swagger hele HTTP-rutesektionen med en overskrift, der læser "standard". Du kan ændre dette ved at annotere din controller-klasse med @ApiTags dekoratør og sender dit foretrukne tag som argument.
Ligesom:
// demo.controller.ts
importere { ApiTags } fra '@nestjs/swagger';
@ApiTags('Demo')
@Kontroller('demo')
eksportklasse DemoController {
Skema-sektionen indeholder dataoverførselsobjekterne i din API. I øjeblikket inkluderer brugerfladen ingen af deres egenskaber.
For at erklære deres egenskaber i brugergrænsefladen skal du blot tilføje dekoratører. Anmærk hver påkrævet egenskab med @ApiProperty dekoratør. Anmærk valgfrie egenskaber med @ApiPropertyValgfri dekoratør.
For eksempel:
// create-demo.dto.ts
importere { ApiProperty, ApiPropertyOptional } fra '@nestjs/swagger';
eksportklasse CreateDemoDto {
@ApiProperty({
type: Snor,
beskrivelse: 'Dette er en påkrævet egenskab',
})
ejendom: snor;
@ApiPropertyValgfri({
type: Snor,
beskrivelse: 'Dette er en valgfri ejendom',
})
valgfri egenskab: snor;
}
@ApiProperty- og @ApiPropertyOptional-dekoratørerne accepterer hver et option-objekt. Dette objekt beskriver den egenskab, der følger nedenfor.
Bemærk, at optionsobjektet bruger JavaScript, ikke TypeScript. Derfor JavaScript-typeerklæringerne (dvs. streng, ikke streng).
Annotering af dataoverførselsobjektets egenskaber tilføjer et eksempel på de forventede data til sektionen Skemaer. Den opdaterer også den tilknyttede HTTP-rute med et eksempel på de forventede data.
Trin 5: Indstil API-svar
I din controller-klasse skal du bruge @ApiResponse dekoratører til at dokumentere alle potentielle svar for hver HTTP-rute. For hvert endepunkt beskriver de forskellige @ApiResponse-dekoratører, hvilken type svar man kan forvente.
Vi har forklaret almindelige HTTP-svar, hvis du ikke er bekendt med, hvad de betyder.
@ApiResponse-dekoratørerne accepterer et valgfrit objekt, der beskriver svaret.
Fælles POST-svar
For en POST-anmodning omfatter de sandsynlige svar:
- ApiCreatedResponse, for vellykkede 201 oprettede svar.
- ApiUnprocessableEnityResponse, for mislykkede 422 ubearbejdelige entitetssvar.
- ApiForbiddenResponse, for 403 forbudte svar.
For eksempel:
// demo.controller.ts
@Stolpe()
@ApiCreatedResponse({ beskrivelse: 'Oprettet med succes' })
@ApiUnprocessableEntityResponse({ description: 'Dårlig anmodning' })
@ApiForbiddenResponse({ beskrivelse: 'Uautoriseret anmodning' })
skab(@Legeme() createDemoDto: CreateDemoDto) {
Vend tilbagedette.demoService.create (createDemoDto);
}
Fælles GET-svar
For GET-anmodninger omfatter de sandsynlige svar:
- ApiOkResponse, for 200 ok svar.
- ApiForbiddenResponse, for 403 forbudte svar.
- ApiNotFoundResponse, for 404 ikke-fundne svar.
For eksempel:
// demo.controller.ts
@Få()
@ApiOkResponse({ beskrivelse: 'Ressourcerne blev returneret med succes' })
@ApiForbiddenResponse({ beskrivelse: 'Uautoriseret anmodning' })
findAll() {
Vend tilbagedette.demoService.findAll();
}
@Få(':id')
@ApiOkResponse({ beskrivelse: 'Ressourcen blev returneret med succes' })
@ApiForbiddenResponse({ beskrivelse: 'Uautoriseret anmodning' })
@ApiNotFoundResponse({ beskrivelse: 'Ressource ikke fundet' })
find en(@Param('jeg gjorde: snor) {
Vend tilbagedette.demoService.findOne(+id);
}
Fælles PATCH og UPDATE-svar
For PATCH- og UPDATE-anmodninger omfatter de sandsynlige svar:
- ApiOkResponse, for 200 ok svar.
- ApiNotFoundResponse, for 404 ikke-fundne svar.
- ApiUnprocessibleEntityResponse, for mislykkede 422 ubearbejdelige entitetssvar.
- ApiForbiddenResponse, for 403 forbudte svar.
For eksempel:
// demo.controller.ts
@Lappe(':id')
@ApiOkResponse({ beskrivelse: 'Ressourcen blev opdateret' })
@ApiNotFoundResponse({ beskrivelse: 'Ressource ikke fundet' })
@ApiForbiddenResponse({ beskrivelse: 'Uautoriseret anmodning' })
@ApiUnprocessableEntityResponse({ description: 'Dårlig anmodning' })
opdatering(@Param('jeg gjorde: snor, @Legeme() updateDemoDto: UpdateDemoDto) {
Vend tilbagedette.demoService.update(+id, updateDemoDto);
}
Almindelige SLET-svar
For SLET-anmodninger omfatter de sandsynlige svar:
- ApiOkResponse, for 200 ok svar.
- ApiForbiddenResponse, for 403 forbudte svar.
- ApiNotFoundResponse, for 404 ikke-fundne svar.
For eksempel:
// demo.controller.ts
@Slet(':id')
@ApiOkResponse({ beskrivelse: 'Ressourcen blev returneret med succes' })
@ApiForbiddenResponse({ beskrivelse: 'Uautoriseret anmodning' })
@ApiNotFoundResponse({ beskrivelse: 'Ressource ikke fundet' })
fjerne(@Param('jeg gjorde: snor) {
Vend tilbagedette.demoService.remove(+id);
}
Disse dekoratører udfylder din dokumentation med mulige svar. Du kan se dem ved at bruge rullemenuen ved siden af hver rute.
Se din dokumentation
Når din opsætning er færdig, kan du se din dokumentation på lokal vært:
Det væsentlige i Swagger API-dokumentation er beskrivelsen, svartyperne og skemadefinitionen. Dette er de grundlæggende ting, der skal til for at skabe god API-dokumentation.
