Swagger je brezplačen, odprtokodni okvir za ustvarjanje interaktivne in uporabniku prijazne dokumentacije API. Ustvari interaktivne spletne strani, ki vam omogočajo testiranje API-ja z različnimi vhodi.
Swagger podpira obremenitve JSON in XML. Dokumentacija, ki jo ustvari, je primerna za uporabo razvijalcem in nerazvijalcem.
Svoje spletne API-je NestJS lahko dokumentirate prek Swaggerja z uporabo preprostih dekoraterjev, ne da bi morali zapustiti svoj IDE.
1. korak: Ustvarjanje API-ja
Preden začnete, morate ustvariti demo API, da bo Swagger ustvaril svojo dokumentacijo.
Demo API boste ustvarili iz nič z uporabo NestJS CLI.
Najprej ustvarite nov projekt NestJS tako, da zaženete:
gnezdo novo <ime-vašega-projekta>
Nato spremenite imenik v že ustvarjen projekt tako, da zaženete:
cd <ime-vašega-projekta>
Nato boste ustvarili API REST s CLI tako, da boste zagnali:
nest create resource demo --no-spec
Videli boste poizvedbo z vprašanjem "Katero transportno plast uporabljate?" izberite REST API.
Videli boste drugo poizvedbo z vprašanjem: »Ali želite ustvariti vstopne točke CRUD?« Vrsta
Y in udaril Vnesite.Zgornji ukaz ustvari popolnoma funkcionalen REST API s končnimi točkami CRUD in brez testnih datotek enote. Zato je --no-spec zastavico v zgornjem ukazu.
2. korak: Namestite Swagger
Namestite Swagger in njegovo knjižnico Express UI tako, da zaženete:
npm namestite--save @nestjs/swagger swagger-ui-express
3. korak: Konfigurirajte Swagger
V vašem main.ts datoteka, uvoz SwaggerModule in DocumentBuilder od @nestjs/swagger.
DocumentBuilder pomaga pri strukturiranju osnovnega dokumenta. Zagotavlja več metod, ki jih lahko povežete v verigo in zaprete z graditi metoda.
Te metode omogočajo konfiguracijo številnih atributov, kot so naslov, opis in različica.
Ustvariti konfiguracija spremenljivka objekta v vašem bootstrap deluje takole:
konst konfiguracija = novo DocumentBuilder()
.setTitle('Demo API')
.setDescription('Demo API z CRUD funkcionalnost')
.setVersion('1.0')
.build();
Nov primerek DocumentBuilderja ustvari osnovni dokument, ki se ujema z Specifikacija OpenAPI. Ta primerek lahko nato uporabite za nastavitev naslova, opisa in različice prek ustreznih metod.
Nato boste morali ustvariti celoten dokument z vsemi potmi HTTP, definiranimi z uporabo osnovnega dokumenta.
Če želite to narediti, pokličite createDocument metoda na SwaggerModule. createDocument sprejme dva argumenta: primerek aplikacije in objekt možnosti Swagger. Shranite rezultat tega klica v spremenljivko za kasnejšo uporabo:
konstdokument = SwaggerModule.createDocument (aplikacija, konfiguracija);
Nato pokličite nastaviti metoda na SwaggerModule. Metoda nastavitve ima tri argumente:
- Pot uporabniškega vmesnika Swagger. Po dogovoru lahko uporabite »api«.
- Primer aplikacije
- Celoten dokument
Poleg tega ima metoda namestitve izbirni predmet možnosti. glej Dokumentacija NestJS o možnostih dokumenta Swagger če želite izvedeti več o tem.
takole:
SwaggerModule.setup('api', aplikacija, dokument);
Zaženite aplikacijo in pojdite na http://localhost:
Na strani bi morali videti prikazan uporabniški vmesnik Swagger.
Zgornja slika je privzeti pogled uporabniškega vmesnika Swagger z definiranimi vsemi potmi HTTP v vašem krmilniku. Morali ga boste prilagoditi, da bo ustrezal vašim funkcijam API-ja.
4. korak: prilagodite lastnosti API-ja
Swagger privzeto doda predpono celotnemu razdelku poti HTTP z naslovom, ki se glasi »privzeto«. To lahko spremenite tako, da svoj razred krmilnika označite z @ApiTags dekoraterja in posredovanje želene oznake kot argumenta.
takole:
// demo.controller.ts
uvoz {ApiTags} od '@nestjs/swagger';
@ApiTags('Demo')
@Krmilnik('demo')
izvozrazred DemoController {
Razdelek Sheme vsebuje objekte za prenos podatkov v vašem API-ju. Trenutno uporabniški vmesnik ne vključuje nobene od njihovih lastnosti.
Če želite deklarirati njihove lastnosti v uporabniškem vmesniku, preprosto dodajte dekoratorje. Vsako zahtevano lastnost označite z @ApiProperty dekorater. Izbirne lastnosti označite z @ApiPropertyOptional dekorater.
Na primer:
// create-demo.dto.ts
uvoz {ApiProperty, ApiPropertyOptional} od '@nestjs/swagger';
izvozrazred CreateDemoDto {
@ApiProperty({
vrsta: Vrvica,
opis: 'To je zahtevana lastnost',
})
lastnina: vrvica;
@ApiPropertyOptional({
vrsta: Vrvica,
opis: 'To je neobvezna lastnost',
})
neobvezna lastnost: vrvica;
}
Vsak dekorator @ApiProperty in @ApiPropertyOptional sprejmeta objekt možnosti. Ta objekt opisuje lastnost, ki sledi spodaj.
Upoštevajte, da predmet možnosti uporablja JavaScript, ne TypeScript. Od tod tudi deklaracije vrste JavaScript (tj. Niz, ne niz).
Označevanje lastnosti objekta za prenos podatkov doda primer pričakovanih podatkov v razdelek Sheme. Prav tako posodobi povezano pot HTTP s primerom pričakovanih podatkov.
5. korak: Nastavite odgovore API-ja
V svojem razredu krmilnika uporabite @ApiResponse dekoratorji za dokumentiranje vseh možnih odgovorov za vsako pot HTTP. Za vsako končno točko različni dekoraterji @ApiResponse opisujejo vrsto odgovorov, ki jih je treba pričakovati.
Pojasnili smo pogosti odgovori HTTP, če niste seznanjeni s tem, kaj pomenijo.
Okraševalci @ApiResponse sprejmejo izbirni objekt, ki opisuje odgovor.
Pogosti odgovori POST
Za zahtevo POST verjetni odgovori vključujejo:
- ApiCreatedResponse, za uspešen 201 ustvarjen odgovor.
- ApiUnprocessableEnityResponse, za neuspešne odzive 422 neobdelanih entitet.
- ApiForbiddenResponse, za 403 prepovedane odgovore.
Na primer:
// demo.controller.ts
@Objava()
@ApiCreatedResponse({ opis: 'Uspešno ustvarjeno' })
@ApiUnprocessableEntityResponse({ opis: 'Slaba zahteva' })
@ApiForbiddenResponse({ opis: 'Nepooblaščena zahteva' })
ustvari (@Telo() createDemoDto: CreateDemoDto) {
vrnitevto.demoService.create (createDemoDto);
}
Pogosti odgovori GET
Za zahteve GET verjetni odgovori vključujejo:
- ApiOkResponse, za 200 ok odgovorov.
- ApiForbiddenResponse, za 403 prepovedane odgovore.
- ApiNotFoundResponse, za 404 ne-najdenih odgovorov.
Na primer:
// demo.controller.ts
@Get()
@ApiOkResponse({ opis: 'Viri so bili uspešno vrnjeni' })
@ApiForbiddenResponse({ opis: 'Nepooblaščena zahteva' })
findAll() {
vrnitevto.demoService.findAll();
}
@Get(':id')
@ApiOkResponse({ opis: 'Vir je bil uspešno vrnjen' })
@ApiForbiddenResponse({ opis: 'Nepooblaščena zahteva' })
@ApiNotFoundResponse({ opis: 'Vira ni bilo mogoče najti' })
findOne(@Param('jaz sem: vrvica) {
vrnitevto.demoService.findOne(+id);
}
Pogosta odziva PATCH in UPDATE
Za zahteve PATCH in UPDATE verjetni odgovori vključujejo:
- ApiOkResponse, za 200 ok odgovorov.
- ApiNotFoundResponse, za 404 ne-najdenih odgovorov.
- ApiUnprocessibleEntityResponse, za neuspešne odzive 422 neobdelanih entitet.
- ApiForbiddenResponse, za 403 prepovedane odgovore.
Na primer:
// demo.controller.ts
@Patch(':id')
@ApiOkResponse({ opis: 'Vir je bil uspešno posodobljen' })
@ApiNotFoundResponse({ opis: 'Vira ni bilo mogoče najti' })
@ApiForbiddenResponse({ opis: 'Nepooblaščena zahteva' })
@ApiUnprocessableEntityResponse({ opis: 'Slaba zahteva' })
nadgradnja(@Param('jaz sem: vrvica, @Telo() updateDemoDto: UpdateDemoDto) {
vrnitevto.demoService.update(+id, updateDemoDto);
}
Pogosti odgovori DELETE
Za zahteve DELETE verjetni odgovori vključujejo:
- ApiOkResponse, za 200 ok odgovorov.
- ApiForbiddenResponse, za 403 prepovedane odgovore.
- ApiNotFoundResponse, za 404 ne-najdenih odgovorov.
Na primer:
// demo.controller.ts
@Izbriši(':id')
@ApiOkResponse({ opis: 'Vir je bil uspešno vrnjen' })
@ApiForbiddenResponse({ opis: 'Nepooblaščena zahteva' })
@ApiNotFoundResponse({ opis: 'Vira ni bilo mogoče najti' })
Odstrani(@Param('jaz sem: vrvica) {
vrnitevto.demoService.remove(+id);
}
Ti dekoraterji zapolnijo vašo dokumentacijo z možnimi odgovori. Ogledate si jih lahko s spustnim menijem ob vsaki poti.
Ogled vaše dokumentacije
Ko je nastavitev končana, si lahko ogledate dokumentacijo na lokalni gostitelj:
Osnove dokumentacije Swagger API so opis, vrste odzivov in definicija sheme. To so osnovne stvari, potrebne za ustvarjanje dobre dokumentacije API-ja.
