Swagger är ett gratis ramverk med öppen källkod för att skapa interaktiv och användarvänlig API-dokumentation. Den genererar interaktiva webbsidor som låter dig testa ett API med olika ingångar.
Swagger stöder både JSON- och XML-nyttolaster. Dokumentationen som den genererar är lämplig för utvecklare och icke-utvecklare att använda.
Du kan dokumentera dina NestJS-webb-API: er via Swagger med enkla dekoratörer, utan att behöva lämna din IDE.
Steg 1: Generera API
Innan du börjar måste du skapa ett demo-API som Swagger kommer att generera dess dokumentation.
Du kommer att generera demo-API: et från början med NestJS CLI.
Skapa först ett nytt NestJS-projekt genom att köra:
bo nytt <namnet på ditt projekt>
Ändra sedan katalogen till ditt redan skapade projekt genom att köra:
CD <namnet på ditt projekt>
Därefter genererar du ett REST API med CLI genom att köra:
nest generera resursdemo -- ingen spec
Du kommer att se en fråga som frågar "Vilket transportlager använder du?" Välj REST API.
Du kommer att se en annan fråga som frågar: "Vill du generera CRUD-ingångspunkter?" Typ Y och slå Stiga på.
Kommandot ovan genererar ett fullt fungerande REST API med CRUD-slutpunkter och utan enhetstestfilerna. Därav -- ingen spec flagga i kommandot ovan.
Steg 2: Installera Swagger
Installera Swagger och dess Express UI-bibliotek genom att köra:
npm Installera--spara @nestjs/swagger swagger-ui-express
Steg 3: Konfigurera Swagger
I din main.ts fil, importera SwaggerModule och DocumentBuilder från @nestjs/swagger.
DocumentBuilder hjälper till att strukturera ett basdokument. Det ger flera metoder som du kan koppla ihop och stänga med bygga metod.
Dessa metoder möjliggör konfiguration av många attribut, såsom titel, beskrivning och version.
Skapa en config objektvariabel i din bootstrap fungerar så här:
konst config = ny DocumentBuilder()
.setTitle('Demo API')
.setDescription('A Demo API med CRUD-funktionalitet')
.setVersion('1.0')
.bygga();
En ny instans av DocumentBuilder skapar ett basdokument som matchar OpenAPI-specifikation. Du kan sedan använda den här instansen för att ställa in titel, beskrivning och version via deras lämpliga metoder.
Därefter måste du skapa ett komplett dokument med alla HTTP-rutter definierade med basdokumentet.
För att göra detta, ring skapa Dokument metod på SwaggerModule. createDocument accepterar två argument: en applikationsinstans och ett Swagger options-objekt. Lagra resultatet av detta anrop i en variabel för senare användning:
konstdokumentera = SwaggerModule.createDocument (app, config);
Ring sedan till uppstart metod på SwaggerModule. Inställningsmetoden tar in tre argument:
- Swagger UI-vägen. Enligt konvention kan du använda "api".
- En applikationsinstans
- Hela dokumentet
Dessutom tar installationsmetoden ett valfritt alternativobjekt. Ser NestJS dokumentation om Swagger-dokumentalternativ för att lära dig mer om det.
Såhär:
SwaggerModule.setup('api', app, dokument);
Starta din ansökan och gå till http://localhost:
Du bör se Swagger UI visas på sidan.
Bilden ovan är standardvyn för Swagger UI, med alla HTTP-rutter i din kontroller definierade. Du måste anpassa den för att passa din API-funktionalitet.
Steg 4: Anpassa API-egenskaper
Som standard prefixar Swagger hela HTTP-ruttavsnittet med en rubrik som lyder "standard". Du kan ändra detta genom att kommentera din kontrollklass med @ApiTags dekoratör och skicka din föredragna tagg som ett argument.
Såhär:
// demo.controller.ts
importera { ApiTags } från '@nestjs/swagger';
@ApiTags('Demo')
@Kontroller('demo')
exporteraklass DemoController {
Sektionen Schema innehåller dataöverföringsobjekten i ditt API. För närvarande innehåller användargränssnittet ingen av deras egenskaper.
För att deklarera deras egenskaper i användargränssnittet, lägg helt enkelt till dekoratörer. Anteckna varje nödvändig egenskap med @ApiProperty dekoratör. Annotera valfria egenskaper med @ApiPropertyValfritt dekoratör.
Till exempel:
// create-demo.dto.ts
importera { ApiProperty, ApiPropertyOptional } från '@nestjs/swagger';
exporteraklass CreateDemoDto {
@ApiProperty({
typ: Sträng,
description: 'Detta är en obligatorisk egenskap',
})
fast egendom: sträng;
@ApiPropertyValfritt({
typ: Sträng,
description: 'Detta är en valfri egenskap',
})
optionalProperty: sträng;
}
@ApiProperty- och @ApiPropertyOptional-dekoratörerna accepterar varsitt alternativobjekt. Det objektet beskriver egenskapen som följer nedan.
Observera att optionsobjektet använder JavaScript, inte TypeScript. Därav JavaScript-typdeklarationerna (dvs. String, inte sträng).
Genom att kommentera dataöverföringsobjektets egenskaper läggs ett exempel på förväntad data till i avsnittet Schema. Den uppdaterar också den associerade HTTP-rutten med ett exempel på förväntad data.
Steg 5: Ställ in API-svar
I din controllerklass, använd @ApiResponse dekoratörer för att dokumentera alla potentiella svar för varje HTTP-rutt. För varje slutpunkt beskriver de olika @ApiResponse-dekoratörerna vilken typ av svar som kan förväntas.
Vi har förklarat vanliga HTTP-svar, om du inte är bekant med vad de betyder.
@ApiResponse-dekoratörerna accepterar ett valfritt objekt som beskriver svaret.
Vanliga POST-svar
För en POST-begäran inkluderar de troliga svaren:
- ApiCreatedResponse, för framgångsrika 201 skapade svar.
- ApiUnprocessableEnityResponse, för misslyckade 422 obearbetningsbara entitetssvar.
- ApiForbiddenResponse, för 403 förbjudna svar.
Till exempel:
// demo.controller.ts
@Posta()
@ApiCreatedResponse({ description: 'Created Successfully' })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
@ApiForbiddenResponse({ description: 'Obehörig begäran' })
skapa(@Kropp() createDemoDto: CreateDemoDto) {
lämna tillbakadetta.demoService.create (createDemoDto);
}
Vanliga GET-svar
För GET-förfrågningar inkluderar de troliga svaren:
- ApiOkResponse, för 200 ok svar.
- ApiForbiddenResponse, för 403 förbjudna svar.
- ApiNotFoundResponse, för 404 svar som inte hittades.
Till exempel:
// demo.controller.ts
@Skaffa sig()
@ApiOkResponse({ description: 'Resurserna returnerades framgångsrikt' })
@ApiForbiddenResponse({ description: 'Obehörig begäran' })
hitta alla() {
lämna tillbakadetta.demoService.findAll();
}
@Skaffa sig(':id')
@ApiOkResponse({ beskrivning: 'Resursen returnerades framgångsrikt' })
@ApiForbiddenResponse({ description: 'Obehörig begäran' })
@ApiNotFoundResponse({ description: 'Resource not found' })
hitta en(@Param('jag gjorde: sträng) {
lämna tillbakadetta.demoService.findOne(+id);
}
Vanliga PATCH- och UPDATE-svar
För PATCH- och UPDATE-förfrågningar inkluderar de troliga svaren:
- ApiOkResponse, för 200 ok svar.
- ApiNotFoundResponse, för 404 svar som inte hittades.
- ApiUnprocessibleEntityResponse, för misslyckade 422 obearbetningsbara entitetssvar.
- ApiForbiddenResponse, för 403 förbjudna svar.
Till exempel:
// demo.controller.ts
@Lappa(':id')
@ApiOkResponse({ beskrivning: 'Resursen uppdaterades framgångsrikt' })
@ApiNotFoundResponse({ description: 'Resource not found' })
@ApiForbiddenResponse({ description: 'Obehörig begäran' })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
uppdatering(@Param('jag gjorde: sträng, @Kropp() updateDemoDto: UpdateDemoDto) {
lämna tillbakadetta.demoService.update(+id, updateDemoDto);
}
Vanliga DELETE-svar
För DELETE-förfrågningar inkluderar de troliga svaren:
- ApiOkResponse, för 200 ok svar.
- ApiForbiddenResponse, för 403 förbjudna svar.
- ApiNotFoundResponse, för 404 svar som inte hittades.
Till exempel:
// demo.controller.ts
@Radera(':id')
@ApiOkResponse({ beskrivning: 'Resursen returnerades framgångsrikt' })
@ApiForbiddenResponse({ description: 'Obehörig begäran' })
@ApiNotFoundResponse({ description: 'Resource not found' })
ta bort(@Param('jag gjorde: sträng) {
lämna tillbakadetta.demoService.remove(+id);
}
Dessa dekoratörer fyller i din dokumentation med möjliga svar. Du kan se dem med hjälp av rullgardinsmenyn bredvid varje rutt.
Visa din dokumentation
När din installation är klar kan du se din dokumentation på lokal värd:
Det väsentliga med Swagger API-dokumentation är beskrivningen, svarstyperna och schemadefinitionen. Det här är de grundläggande sakerna som behövs för att skapa bra API-dokumentation.
