Swagger is een gratis, open-source framework voor het maken van interactieve en gebruiksvriendelijke API-documentatie. Het genereert interactieve webpagina's waarmee u een API met verschillende invoer kunt testen.
Swagger ondersteunt zowel JSON- als XML-payloads. De documentatie die het genereert is geschikt voor ontwikkelaars en niet-ontwikkelaars om te gebruiken.
Je kunt je NestJS-web-API's documenteren via Swagger met behulp van eenvoudige decorateurs, zonder dat je je IDE hoeft te verlaten.
Stap 1: De API genereren
Voordat u begint, moet u een demo-API maken die Swagger de documentatie ervan zal genereren.
U genereert de demo-API helemaal opnieuw met behulp van de NestJS CLI.
Genereer eerst een nieuw NestJS-project door het volgende uit te voeren:
nieuw nest <naam-van-uw-project>
Wijzig vervolgens de map in uw reeds gemaakte project door het volgende uit te voeren:
CD <naam-van-uw-project>
Vervolgens genereert u een REST API met de CLI door het volgende uit te voeren:
nest genereer resource demo --no-spec
U ziet een vraag met de vraag: "Welke transportlaag gebruikt u?" selecteer REST-API.
U ziet een andere vraag met de vraag: "Wilt u CRUD-toegangspunten genereren?" Type Y en raak Binnenkomen.
Het bovenstaande commando genereert een volledig functionele REST API met CRUD-eindpunten en zonder de unit-testbestanden. Vandaar dat de --no-spec vlag in de bovenstaande opdracht.
Stap 2: Installeer Swagger
Installeer Swagger en zijn Express UI-bibliotheek door het volgende uit te voeren:
npm installeren--save @nestjs/swagger swagger-ui-express
Stap 3: Swagger configureren
In uw hoofd.ts bestand, import SwaggerModule en DocumentBuilder van @nestjs/swagger.
DocumentBuilder helpt bij het structureren van een basisdocument. Het biedt verschillende methoden die u aan elkaar kunt koppelen en sluiten met de bouwen methode.
Deze methoden maken de configuratie van vele attributen mogelijk, zoals titel, beschrijving en versie.
Maak een configuratie objectvariabele in uw bootstrap functioneren als volgt:
const config = nieuwe DocumentBuilder()
.setTitle('Demo-API')
.setDescription('Een demo-API met CRUD-functionaliteit')
.setVersion('1.0')
.bouwen();
Een nieuw exemplaar van DocumentBuilder maakt een basisdocument dat overeenkomt met de OpenAPI-specificatie. U kunt deze instantie vervolgens gebruiken om de titel, beschrijving en versie in te stellen via de juiste methoden.
Vervolgens moet u een compleet document maken met alle HTTP-routes die zijn gedefinieerd met behulp van het basisdocument.
Bel hiervoor de creërenDocument methode op SwaggerModule. createDocument accepteert twee argumenten: een toepassingsinstantie en een Swagger-optieobject. Sla het resultaat van deze aanroep op in een variabele voor later gebruik:
constdocument = SwaggerModule.createDocument (app, configuratie);
Bel vervolgens de opstelling methode op SwaggerModule. De setup-methode heeft drie argumenten:
- Het Swagger UI-pad. Volgens afspraak kunt u "api" gebruiken.
- Een applicatie-instantie
- Het volledige document
Bovendien neemt de setup-methode een optioneel options-object. Zien NestJS-documentatie over Swagger-documentopties om er meer over te weten te komen.
Zoals zo:
SwaggerModule.setup('api', app, document);
Start uw aanvraag en ga naar http://localhost:
U zou de Swagger-gebruikersinterface op de pagina moeten zien.
De afbeelding hierboven is de standaardweergave van de Swagger-gebruikersinterface, waarbij alle HTTP-routes in uw controller zijn gedefinieerd. U moet het aanpassen aan uw API-functionaliteit.
Stap 4: API-eigenschappen aanpassen
Standaard laat Swagger de volledige HTTP-routesectie voorafgaan met een kop die "standaard" luidt. U kunt dit wijzigen door uw controllerklasse te annoteren met de @ApiTags decorateur en het doorgeven van uw favoriete tag als argument.
Zoals zo:
// demo.controller.ts
importeren { ApiTags } van '@nestjs/swagger';
@ApiTags('Demo')
@Controller('demo')
exporterenklas DemoController {
De sectie Schema's bevat de gegevensoverdrachtobjecten in uw API. Momenteel bevat de gebruikersinterface geen van hun eigenschappen.
Om hun eigenschappen in de gebruikersinterface te declareren, voegt u eenvoudig decorateurs toe. Annoteer elke vereiste eigenschap met de @ApiProperty decorateur. Annoteer optionele eigenschappen met de @ApiPropertyOptioneel decorateur.
Bijvoorbeeld:
// create-demo.dto.ts
importeren { ApiProperty, ApiPropertyOptioneel } van '@nestjs/swagger';
exporterenklas CreateDemoDto {
@ApiProperty({
type: Snaar,
omschrijving: 'Dit is een vereiste eigenschap',
})
eigendom: snaar;
@ApiPropertyOptioneel({
type: Snaar,
omschrijving: 'Dit is een optionele eigenschap',
})
optioneelEigenschap: snaar;
}
De @ApiProperty- en @ApiPropertyOptional-decorateurs accepteren elk een optieobject. Dat object beschrijft de eigenschap die hieronder volgt.
Merk op dat het options-object JavaScript gebruikt, niet TypeScript. Vandaar de declaraties van het JavaScript-type (d.w.z. String, niet string).
Door de eigenschappen van het gegevensoverdrachtobject te annoteren, wordt een voorbeeld van de verwachte gegevens toegevoegd aan de sectie Schema's. Het werkt ook de bijbehorende HTTP-route bij met een voorbeeld van de verwachte gegevens.
Stap 5: API-antwoorden instellen
Gebruik in je controllerklasse de @ApiResponse decorateurs om alle mogelijke reacties voor elke HTTP-route te documenteren. Voor elk eindpunt beschrijven de verschillende @ApiResponse-decorateurs het type reacties dat u kunt verwachten.
We hebben uitgelegd veelvoorkomende HTTP-antwoorden, voor het geval u niet bekend bent met wat ze betekenen.
De @ApiResponse-decorateurs accepteren een optioneel object dat het antwoord beschrijft.
Algemene POST-reacties
Voor een POST-verzoek zijn de waarschijnlijke reacties:
- ApiCreatedReactie, voor succesvolle 201 gemaakte reacties.
- ApiUnprocessableEnityResponse, voor mislukte 422 onverwerkbare entiteitsreacties.
- ApiForbiddenReactie, voor 403 verboden antwoorden.
Bijvoorbeeld:
// demo.controller.ts
@Na()
@ApiCreatedResponse({ description: 'Succesvol aangemaakt' })
@ApiUnprocessableEntityResponse({ omschrijving: 'Slecht verzoek' })
@ApiForbiddenResponse({ omschrijving: 'Ongeautoriseerd verzoek' })
creëren(@Lichaam() createDemoDto: CreateDemoDto) {
opbrengstdeze.demoService.create (createDemoDto);
}
Algemene GET-reacties
Voor GET-verzoeken zijn de waarschijnlijke reacties:
- ApiOkReactie, voor 200 ok reacties.
- ApiForbiddenReactie, voor 403 verboden antwoorden.
- ApiNiet gevondenReactie, voor 404 niet gevonden reacties.
Bijvoorbeeld:
// demo.controller.ts
@Krijgen()
@ApiOkResponse({ description: 'De bronnen zijn succesvol geretourneerd' })
@ApiForbiddenResponse({ omschrijving: 'Ongeautoriseerd verzoek' })
vind alle() {
opbrengstdeze.demoService.findAll();
}
@Krijgen(':ID kaart')
@ApiOkResponse({ description: 'De bron is succesvol geretourneerd' })
@ApiForbiddenResponse({ omschrijving: 'Ongeautoriseerd verzoek' })
@ApiNotFoundResponse({ omschrijving: 'Bron niet gevonden' })
vind een(@Param('ik deed: snaar) {
opbrengstdeze.demoService.findOne(+id);
}
Algemene PATCH- en UPDATE-reacties
Voor PATCH- en UPDATE-verzoeken zijn de waarschijnlijke reacties:
- ApiOkReactie, voor 200 ok reacties.
- ApiNiet gevondenReactie, voor 404 niet gevonden reacties.
- ApiUnprocessibleEntityResponse, voor mislukte 422 onverwerkbare entiteitsreacties.
- ApiForbiddenReactie, voor 403 verboden antwoorden.
Bijvoorbeeld:
// demo.controller.ts
@Lapje(':ID kaart')
@ApiOkResponse({ description: 'De bron is succesvol geüpdatet' })
@ApiNotFoundResponse({ omschrijving: 'Bron niet gevonden' })
@ApiForbiddenResponse({ omschrijving: 'Ongeautoriseerd verzoek' })
@ApiUnprocessableEntityResponse({ omschrijving: 'Slecht verzoek' })
update(@Param('ik deed: snaar, @Lichaam() updateDemoDto: UpdateDemoDto) {
opbrengstdeze.demoService.update(+id, updateDemoDto);
}
Algemene DELETE-reacties
Voor DELETE-verzoeken zijn de waarschijnlijke reacties:
- ApiOkReactie, voor 200 ok reacties.
- ApiForbiddenReactie, voor 403 verboden antwoorden.
- ApiNiet gevondenReactie, voor 404 niet gevonden reacties.
Bijvoorbeeld:
// demo.controller.ts
@Verwijderen(':ID kaart')
@ApiOkResponse({ description: 'De bron is succesvol geretourneerd' })
@ApiForbiddenResponse({ omschrijving: 'Ongeautoriseerd verzoek' })
@ApiNotFoundResponse({ omschrijving: 'Bron niet gevonden' })
verwijderen(@Param('ik deed: snaar) {
opbrengstdeze.demoService.remove(+id);
}
Deze decorateurs vullen uw documentatie met mogelijke antwoorden. Je kunt ze bekijken met behulp van de vervolgkeuzelijst naast elke route.
Uw documentatie bekijken
Wanneer uw installatie is voltooid, kunt u uw documentatie bekijken op: lokale host:
De essentie van de Swagger API-documentatie zijn de beschrijving, antwoordtypen en schemadefinitie. Dit zijn de basisdingen die nodig zijn om goede API-documentatie te maken.