Swagger on tasuta avatud lähtekoodiga raamistik interaktiivse ja kasutajasõbraliku API dokumentatsiooni loomiseks. See loob interaktiivseid veebilehti, mis võimaldavad testida API-d erinevate sisenditega.
Swagger toetab nii JSON- kui ka XML-koormust. Selle loodud dokumentatsioon sobib kasutamiseks nii arendajatele kui ka mittearendajatele.
Saate dokumenteerida oma NestJS-i veebi API-sid Swaggeri kaudu lihtsate dekoraatorite abil, ilma et peaksite oma IDE-st lahkuma.
1. samm: API loomine
Enne alustamist peate looma demo API, mille Swagger loob selle dokumentatsiooni.
Saate luua demo API nullist, kasutades NestJS CLI-d.
Esiteks looge uus NestJS-projekt, käivitades:
pesa uus <teie projekti nimi>
Seejärel muutke kataloog oma juba loodud projektiks, käivitades:
cd <teie projekti nimi>
Järgmisena loote CLI-ga REST API, käivitades:
nest genereerida ressursi demo --no-spets
Näete päringut "Millist transpordikihti te kasutate?" vali REST API.
Näete teist päringut, mis küsib: "Kas soovite luua CRUD-i sisenemispunkte?" Tüüp Y ja tabas Sisenema.
Ülaltoodud käsk genereerib täielikult toimiv REST API CRUD-i lõpp-punktidega ja ilma üksuse testfailideta. Seega, --no-spets lipp ülalolevas käsus.
2. samm: installige Swagger
Installige Swagger ja selle Express UI teek, käivitades:
npm installida--save @nestjs/swagger swagger-ui-express
3. samm: konfigureerige Swagger
Sinu main.ts fail, import Swaggeri moodul ja DocumentBuilder alates @nestjs/swagger.
DocumentBuilder aitab alusdokumendi struktureerida. See pakub mitmeid meetodeid, mida saate ühendada ja sulgeda ehitada meetod.
Need meetodid võimaldavad konfigureerida paljusid atribuute, nagu pealkiri, kirjeldus ja versioon.
Loo konfig objekti muutuja teie bootstrap toimib nii:
konst konfiguratsioon = uus DocumentBuilder()
.setTitle('Demo API')
.setDescription('Demo API koos CRUD-funktsioon")
.setVersion('1.0')
.build();
DocumentBuilderi uus eksemplar loob alusdokumendi, mis vastab OpenAPI spetsifikatsioon. Seejärel saate seda eksemplari kasutada pealkirja, kirjelduse ja versiooni määramiseks sobivate meetodite abil.
Järgmisena peate looma täieliku dokumendi kõigi HTTP-marsruutide abil, mis on määratletud põhidokumendi abil.
Selleks helistage loo dokument meetod SwaggerModule'is. createDocument aktsepteerib kahte argumenti: rakenduse eksemplari ja Swaggeri suvandite objekti. Salvestage selle kõne tulemus hilisemaks kasutamiseks muutujas:
konstdokument = SwaggerModule.createDocument (rakendus, konfiguratsioon);
Järgmisena helistage seadistamine meetod SwaggerModule'is. Seadistusmeetodil on kolm argumenti:
- Swaggeri kasutajaliidese tee. Tavapäraselt saate kasutada "api".
- Rakenduse eksemplar
- Täielik dokument
Lisaks võtab häälestusmeetod valikuliste suvandite objekti. Vaata NestJS-i dokumentatsioon Swaggeri dokumendivalikute kohta selle kohta lisateabe saamiseks.
Nagu nii:
SwaggerModule.setup('api', rakendus, dokument);
Käivitage oma rakendus ja minge aadressile http://localhost:
Peaksite lehel nägema Swaggeri kasutajaliidest.
Ülaltoodud pilt on Swaggeri kasutajaliidese vaikevaade, kus kõik teie kontrolleri HTTP-marsruudid on määratletud. Peate seda kohandama, et see sobiks teie API funktsioonidega.
4. samm: kohandage API atribuute
Vaikimisi lisab Swagger kogu HTTP-marsruudi lõigu eesliidese pealkirjaga „vaikimisi”. Saate seda muuta, lisades oma kontrolleriklassile märke @ApiTags sisekujundaja ja argumendina oma eelistatud sildi edastamine.
Nagu nii:
// demo.controller.ts
importida { ApiTags } alates '@nestjs/swagger';
@ApiTags("Demo")
@Controller('demo')
eksportidaklass DemoController {
Jaotis Skeemid sisaldab teie API andmeedastusobjekte. Praegu ei sisalda kasutajaliides ühtegi nende atribuuti.
Nende omaduste deklareerimiseks kasutajaliideses lisage lihtsalt dekoraatorid. Märkige iga nõutav atribuut nupuga @ApiProperty dekoraator. Märkige valikulised atribuudid nupuga @ApiPropertyOptional dekoraator.
Näiteks:
// create-demo.dto.ts
importida { ApiProperty, ApiPropertyOptional } alates '@nestjs/swagger';
eksportidaklass CreateDemoDto {
@ApiProperty({
tüüp: String,
kirjeldus: "See on nõutav omadus",
})
vara: string;
@ApiPropertyOptional({
tüüp: String,
kirjeldus: "See on valikuline omadus",
})
valikuline atribuut: string;
}
@ApiProperty ja @ApiPropertyOptional dekoraatorid aktsepteerivad kumbki suvandite objekti. See objekt kirjeldab alljärgnevat omadust.
Pange tähele, et suvandite objekt kasutab JavaScripti, mitte TypeScripti. Sellest tulenevad JavaScripti tüübi deklaratsioonid (st string, mitte string).
Andmeedastusobjekti atribuutide märkimine lisab oodatud andmete näite jaotisesse Skeemid. Samuti värskendab see seotud HTTP-marsruuti eeldatavate andmete näitega.
5. samm: määrake API vastused
Kasutage oma kontrolleriklassis @ApiResponse dekoraatorid, et dokumenteerida kõik võimalikud vastused iga HTTP-marsruudi jaoks. Iga lõpp-punkti jaoks kirjeldavad erinevad @ApiResponse'i dekoraatorid, millist tüüpi vastuseid oodata.
Oleme selgitanud tavalised HTTP vastused, juhuks kui te pole nende tähendusega kursis.
@ApiResponse'i dekoraatorid aktsepteerivad valikulist objekti, mis kirjeldab vastust.
Levinud POST-vastused
POST-i päringu puhul on tõenäolised vastused järgmised:
- ApiCreatedResponse, edukate 201 loodud vastuse eest.
- ApiUnprocessableEnityResponse, ebaõnnestunud 422 töötlematu olemi vastuse jaoks.
- ApiForbiddenResponse, 403 keelatud vastuse jaoks.
Näiteks:
// demo.controller.ts
@Postitus()
@ApiCreatedResponse({kirjeldus: 'Loodud edukalt' })
@ApiUnprocessableEntityResponse({kirjeldus: 'Bad Request' })
@ApiForbiddenResponse({ kirjeldus: 'Authorized Request' })
loo(@Keha() createDemoDto: CreateDemoDto) {
tagasisee.demoService.create (createDemoDto);
}
Levinud GET-vastused
GET-päringute puhul on tõenäolised vastused järgmised:
- ApiOkResponse, 200 ok vastuse jaoks.
- ApiForbiddenResponse, 403 keelatud vastuse jaoks.
- ApiNotFoundResponse404 mitteleitud vastuse jaoks.
Näiteks:
// demo.controller.ts
@Hangi()
@ApiOkResponse({ kirjeldus: 'Ressursid tagastati edukalt' })
@ApiForbiddenResponse({ kirjeldus: 'Authorized Request' })
leia kõik() {
tagasisee.demoService.findAll();
}
@Hangi(':id')
@ApiOkResponse({kirjeldus: 'Ressursi tagastamine õnnestus' })
@ApiForbiddenResponse({ kirjeldus: 'Authorized Request' })
@ApiNotFoundResponse({kirjeldus: 'Ressursi ei leitud' })
leia üks(@Param('ma tegin: string) {
tagasisee.demoService.findOne(+id);
}
Levinud PATCH ja UPDATE vastused
PATCH ja UPDATE taotluste puhul on tõenäolised vastused järgmised:
- ApiOkResponse, 200 ok vastuse jaoks.
- ApiNotFoundResponse404 mitteleitud vastuse jaoks.
- ApiUnprocessibleEntityResponse, ebaõnnestunud 422 töötlematu olemi vastuse jaoks.
- ApiForbiddenResponse, 403 keelatud vastuse jaoks.
Näiteks:
// demo.controller.ts
@Patch(':id')
@ApiOkResponse({kirjeldus: 'Ressursi värskendamine õnnestus' })
@ApiNotFoundResponse({kirjeldus: 'Ressursi ei leitud' })
@ApiForbiddenResponse({ kirjeldus: 'Authorized Request' })
@ApiUnprocessableEntityResponse({kirjeldus: 'Bad Request' })
värskenda(@Param('ma tegin: string, @Keha() updateDemoDto: UpdateDemoDto) {
tagasisee.demoService.update(+id, updateDemoDto);
}
Levinud DELETE vastused
DELETE taotluste puhul on tõenäolised vastused järgmised:
- ApiOkResponse, 200 ok vastuse jaoks.
- ApiForbiddenResponse, 403 keelatud vastuse jaoks.
- ApiNotFoundResponse404 mitteleitud vastuse jaoks.
Näiteks:
// demo.controller.ts
@Kustuta(':id')
@ApiOkResponse({kirjeldus: 'Ressursi tagastamine õnnestus' })
@ApiForbiddenResponse({ kirjeldus: 'Authorized Request' })
@ApiNotFoundResponse({kirjeldus: 'Ressursi ei leitud' })
eemalda (@Param('ma tegin: string) {
tagasisee.demoService.remove(+id);
}
Need dekoraatorid täidavad teie dokumentatsiooni võimalike vastustega. Saate neid vaadata iga marsruudi kõrval oleva rippmenüü abil.
Teie dokumentatsiooni vaatamine
Kui seadistamine on lõpetatud, saate oma dokumentatsiooni vaadata saidil localhost:
Swagger API dokumentatsiooni põhielemendid on kirjeldus, vastuse tüübid ja skeemi määratlus. Need on põhilised asjad, mida on vaja hea API dokumentatsiooni loomiseks.
