Swagger je besplatan okvir otvorenog koda za stvaranje interaktivne i korisniku prilagođene API dokumentacije. Generira interaktivne web stranice koje vam omogućuju testiranje API-ja s različitim unosima.
Swagger podržava i JSON i XML korisna opterećenja. Dokumentacija koju generira prikladna je za korištenje programerima i onima koji to nisu.
Možete dokumentirati svoje NestJS web API-je putem Swaggera koristeći jednostavne dekoratore, bez potrebe da napuštate svoj IDE.
Korak 1: Generiranje API-ja
Prije početka morate izraditi demo API za koji će Swagger generirati svoju dokumentaciju.
Generirati ćete demo API od nule koristeći NestJS CLI.
Najprije generirajte novi NestJS projekt pokretanjem:
gnijezdo novo <ime-vašeg-projekta>
Zatim promijenite direktorij u svoj već kreirani projekt pokretanjem:
CD <ime-vašeg-projekta>
Zatim ćete generirati REST API s CLI-jem pokretanjem:
gnijezdo generirati resurs demo --bez specifikacije
Vidjet ćete upit s pitanjem "Koji prijenosni sloj koristite?" Odaberi REST API.
Vidjet ćete još jedan upit koji pita: "Želite li generirati CRUD ulazne točke?" Tip Y i udario Unesi.
Gornja naredba generira potpuno funkcionalan REST API s CRUD krajnjim točkama i bez jediničnih testnih datoteka. Stoga, --bez specifikacije zastavica u gornjoj naredbi.
Korak 2: Instalirajte Swagger
Instalirajte Swagger i njegovu Express UI biblioteku pokretanjem:
npm instalirati--save @nestjs/swagger swagger-ui-express
Korak 3: Konfigurirajte Swagger
U vašem glavni.ts datoteka, uvoz SwaggerModule i DocumentBuilder iz @nestjs/swagger.
DocumentBuilder pomaže u strukturiranju osnovnog dokumenta. Nudi nekoliko metoda koje možete ulančati i zatvoriti s izgraditi metoda.
Ove metode omogućuju konfiguraciju mnogih atributa, kao što su naslov, opis i verzija.
Stvoriti konfiguracija varijabla objekta u vašem bootstrap funkcionira ovako:
konst konfiguracija = novi DocumentBuilder()
.setTitle('Demo API')
.setDescription('Demo API s CRUD funkcionalnost')
.setVersion('1.0')
.izgraditi();
Nova instanca DocumentBuilder-a stvara osnovni dokument koji odgovara OpenAPI specifikacija. Zatim možete koristiti ovu instancu za postavljanje naslova, opisa i verzije putem njihovih odgovarajućih metoda.
Zatim ćete morati izraditi potpuni dokument sa svim HTTP rutama definiranim pomoću osnovnog dokumenta.
Da biste to učinili, nazovite createDocument metoda na SwaggerModule. createDocument prihvaća dva argumenta: instancu aplikacije i objekt opcija Swagger. Pohranite rezultat ovog poziva u varijablu za kasniju upotrebu:
konstdokument = SwaggerModule.createDocument (aplikacija, konfiguracija);
Zatim nazovite postaviti metoda na SwaggerModule. Metoda postavljanja uzima tri argumenta:
- Put sučelja Swagger. Prema konvenciji, možete koristiti "api".
- Instanca aplikacije
- Cijeli dokument
Dodatno, metoda postavljanja uzima neobavezni objekt opcija. Vidjeti NestJS-ova dokumentacija o opcijama Swagger dokumenta da saznate više o tome.
ovako:
SwaggerModule.setup('api', aplikacija, dokument);
Pokrenite svoju aplikaciju i idite na http://localhost:
Trebali biste vidjeti Swagger korisničko sučelje prikazano na stranici.
Gornja slika je zadani prikaz korisničkog sučelja Swagger, sa definiranim svim HTTP rutama u vašem kontroleru. Morat ćete ga prilagoditi kako bi odgovarao vašoj funkciji API-ja.
Korak 4: Prilagodite API svojstva
Prema zadanim postavkama, Swagger cijelom odjeljku HTTP rute stavlja prefiks u naslov koji glasi "zadano". To možete promijeniti označavanjem svoje klase kontrolera s @ApiTags dekorater i prosljeđivanje željene oznake kao argumenta.
ovako:
// demo.controller.ts
uvoz {ApiTags} iz '@nestjs/swagger';
@ApiTags('Demo')
@Kontroler('demo')
izvozrazreda DemoController {
Odjeljak Sheme sadrži objekte za prijenos podataka u vašem API-ju. Trenutno korisničko sučelje ne uključuje nijedno od njihovih svojstava.
Da biste deklarirali njihova svojstva u korisničkom sučelju, jednostavno dodajte dekoratore. Svako potrebno svojstvo označite s @ApiProperty dekorater. Označite neobavezna svojstva s @ApiPropertyOptional dekorater.
Na primjer:
// create-demo.dto.ts
uvoz {ApiProperty, ApiPropertyOptional} iz '@nestjs/swagger';
izvozrazreda CreateDemoDto {
@ApiProperty({
tip: Niz,
opis: 'Ovo je potrebno svojstvo',
})
svojstvo: niz;
@ApiPropertyOptional({
tip: Niz,
opis: 'Ovo je izborno svojstvo',
})
izborno svojstvo: niz;
}
@ApiProperty i @ApiPropertyOptional dekoratori prihvaćaju objekt opcija. Taj objekt opisuje svojstvo koje slijedi u nastavku.
Imajte na umu da objekt opcija koristi JavaScript, a ne TypeScript. Otuda i deklaracije vrste JavaScripta (tj. String, a ne string).
Označavanje svojstava objekta za prijenos podataka dodaje primjer očekivanih podataka u odjeljak Sheme. Također ažurira povezanu HTTP rutu s primjerom očekivanih podataka.
Korak 5: Postavite API odgovore
U svojoj klasi kontrolera koristite @ApiResponse dekoratore za dokumentiranje svih potencijalnih odgovora za svaku HTTP rutu. Za svaku krajnju točku različiti @ApiResponse dekoratori opisuju vrstu odgovora koje treba očekivati.
Objasnili smo uobičajeni HTTP odgovori, u slučaju da niste upoznati s njihovim značenjem.
@ApiResponse dekorateri prihvaćaju izborni objekt koji opisuje odgovor.
Uobičajeni POST odgovori
Za POST zahtjev vjerojatni odgovori uključuju:
- ApiCreatedResponse, za uspješan 201 kreiran odgovor.
- ApiUnprocessableEnityResponse, za neuspjela 422 odgovora entiteta koji se ne mogu obraditi.
- ApiForbiddenResponse, za 403 zabranjena odgovora.
Na primjer:
// demo.controller.ts
@Post()
@ApiCreatedResponse({ opis: 'Uspješno stvoreno' })
@ApiUnprocessableEntityResponse({ opis: 'Loš zahtjev' })
@ApiForbiddenResponse({ opis: 'Neovlašteni zahtjev' })
stvoriti(@Tijelo() createDemoDto: CreateDemoDto) {
povratakovaj.demoService.create (createDemoDto);
}
Uobičajeni GET odgovori
Za GET zahtjeve vjerojatni odgovori uključuju:
- ApiOkResponse, za 200 ok odgovora.
- ApiForbiddenResponse, za 403 zabranjena odgovora.
- ApiNotFoundResponse, za 404 odgovora koji nisu pronađeni.
Na primjer:
// demo.controller.ts
@Dobiti()
@ApiOkResponse({ opis: 'Resursi su uspješno vraćeni' })
@ApiForbiddenResponse({ opis: 'Neovlašteni zahtjev' })
findAll() {
povratakovaj.demoService.findAll();
}
@Dobiti(':iskaznica')
@ApiOkResponse({ opis: 'Resurs je uspješno vraćen' })
@ApiForbiddenResponse({ opis: 'Neovlašteni zahtjev' })
@ApiNotFoundResponse({ opis: 'Resurs nije pronađen' })
findOne(@Param('učinio sam: niz) {
povratakovaj.demoService.findOne(+id);
}
Uobičajeni odgovori PATCH i UPDATE
Za zahtjeve PATCH i UPDATE vjerojatni odgovori uključuju:
- ApiOkResponse, za 200 ok odgovora.
- ApiNotFoundResponse, za 404 odgovora koji nisu pronađeni.
- ApiUnprocessibleEntityResponse, za neuspjela 422 odgovora entiteta koji se ne mogu obraditi.
- ApiForbiddenResponse, za 403 zabranjena odgovora.
Na primjer:
// demo.controller.ts
@Zakrpa(':iskaznica')
@ApiOkResponse({ opis: 'Resurs je uspješno ažuriran' })
@ApiNotFoundResponse({ opis: 'Resurs nije pronađen' })
@ApiForbiddenResponse({ opis: 'Neovlašteni zahtjev' })
@ApiUnprocessableEntityResponse({ opis: 'Loš zahtjev' })
Ažuriraj(@Param('učinio sam: niz, @Tijelo() updateDemoDto: UpdateDemoDto) {
povratakovaj.demoService.update(+id, updateDemoDto);
}
Uobičajeni odgovori DELETE
Za zahtjeve DELETE vjerojatni odgovori uključuju:
- ApiOkResponse, za 200 ok odgovora.
- ApiForbiddenResponse, za 403 zabranjena odgovora.
- ApiNotFoundResponse, za 404 odgovora koji nisu pronađeni.
Na primjer:
// demo.controller.ts
@Izbrisati(':iskaznica')
@ApiOkResponse({ opis: 'Resurs je uspješno vraćen' })
@ApiForbiddenResponse({ opis: 'Neovlašteni zahtjev' })
@ApiNotFoundResponse({ opis: 'Resurs nije pronađen' })
ukloniti(@Param('učinio sam: niz) {
povratakovaj.demoService.remove(+id);
}
Ovi dekorateri popunjavaju vašu dokumentaciju mogućim odgovorima. Možete ih vidjeti pomoću padajućeg izbornika uz svaku rutu.
Pregledavanje vaše dokumentacije
Kada je vaše postavljanje dovršeno, možete pogledati svoju dokumentaciju na lokalni domaćin:
Osnove Swagger API dokumentacije su opis, vrste odgovora i definicija sheme. Ovo su osnovne stvari potrebne za izradu dobre API dokumentacije.
