Swagger yra nemokama atvirojo kodo sistema, skirta kurti interaktyvią ir patogią API dokumentaciją. Jis generuoja interaktyvius tinklalapius, leidžiančius išbandyti API su įvairiais įvestimis.
„Swagger“ palaiko JSON ir XML naudingąsias apkrovas. Sukurta dokumentacija tinka kūrėjams ir ne kūrėjams.
Galite dokumentuoti savo NestJS žiniatinklio API naudodami „Swagger“, naudodami paprastus dekoratorius, neišeidami iš IDE.
1 veiksmas: sukurkite API
Prieš pradėdami, turite sukurti demonstracinę API, kurią „Swagger“ sukurs dokumentaciją.
Demonstracinę API sugeneruosite nuo nulio naudodami NestJS CLI.
Pirmiausia sugeneruokite naują NestJS projektą paleisdami:
lizdas naujas <jūsų projekto pavadinimas>
Tada pakeiskite katalogą į jau sukurtą projektą vykdydami:
cd <jūsų projekto pavadinimas>
Tada sugeneruosite REST API su CLI paleisdami:
Nest generuoti išteklių demonstraciją --be specifikacijos
Pamatysite užklausą „Kokį transportavimo sluoksnį naudojate?“ pasirinkite REST API.
Pamatysite kitą užklausą, klausiančią: „Ar norėtumėte sugeneruoti CRUD įvesties taškus? Tipas Y ir pataikė Įeikite.
Sugeneruoja aukščiau pateikta komanda pilnai veikianti REST API su CRUD galutiniais taškais ir be vieneto testo failų. Vadinasi, --be specifikacijos vėliavėlė aukščiau esančioje komandoje.
2 veiksmas: įdiekite „Swagger“.
Įdiekite „Swagger“ ir jo „Express UI“ biblioteką paleisdami:
npm diegti--išsaugoti @nestjs/swagger swagger-ui-express
3 veiksmas: sukonfigūruokite „Swagger“.
Jūsų pagrindinis.ts failas, importas SwaggerModule ir DocumentBuilder iš @nestjs/swagger.
„DocumentBuilder“ padeda struktūrizuoti pagrindinį dokumentą. Jame pateikiami keli metodai, kuriuos galite sujungti ir uždaryti naudodami statyti metodas.
Šie metodai leidžia konfigūruoti daugybę atributų, tokių kaip pavadinimas, aprašas ir versija.
Sukurti konfig objekto kintamasis jūsų bootstrap veikia taip:
konst konfigūracija = naujas DocumentBuilder ()
.setTitle('Demo API')
.setDescription('Demonstracinė API su CRUD funkcija“)
.setVersion('1.0')
.build();
Naujas DocumentBuilder egzempliorius sukuria pagrindinį dokumentą, kuris atitinka OpenAPI specifikacija. Tada galite naudoti šį atvejį, kad nustatytumėte pavadinimą, aprašą ir versiją naudodami atitinkamus metodus.
Tada turėsite sukurti visą dokumentą su visais HTTP maršrutais, apibrėžtais naudojant pagrindinį dokumentą.
Norėdami tai padaryti, skambinkite sukurti dokumentą metodas SwaggerModule. CreateDocument priima du argumentus: programos egzempliorių ir Swagger parinkčių objektą. Išsaugokite šio skambučio rezultatą kintamajame, kad galėtumėte naudoti vėliau:
konstdokumentas = SwaggerModule.createDocument (programa, konfigūracija);
Toliau skambinkite sąranka metodas SwaggerModule. Sąrankos metodas apima tris argumentus:
- „Swagger“ vartotojo sąsajos kelias. Pagal susitarimą galite naudoti „api“.
- Programos pavyzdys
- Visas dokumentas
Be to, sąrankos metodas paima pasirenkamų parinkčių objektą. Pamatyti „NestJS“ dokumentacija apie „Swagger“ dokumento parinktis norėdami sužinoti daugiau apie tai.
Kaip taip:
SwaggerModule.setup('api', programėlė, dokumentas);
Pradėkite savo programą ir eikite į http://localhost:
Puslapyje turėtumėte matyti „Swagger“ vartotojo sąsają.
Aukščiau pateiktas paveikslėlis yra numatytasis „Swagger“ vartotojo sąsajos rodinys, kuriame nurodyti visi jūsų valdiklio HTTP maršrutai. Turėsite jį tinkinti, kad atitiktų jūsų API funkciją.
4 veiksmas: tinkinkite API ypatybes
Pagal numatytuosius nustatymus „Swagger“ prideda visą HTTP maršruto skyrių su antrašte, kuri yra „numatytasis“. Tai galite pakeisti pažymėdami valdiklio klasę su @ApiTags dekoratorius ir kaip argumentą pateikdamas pageidaujamą žymą.
Kaip taip:
// demo.controller.ts
importuoti { ApiTags } iš '@nestjs/swagger';
@ApiTags(„Demonstracija“)
@Controller(„demo“)
eksportuotiklasė DemoController {
Skiltyje Schemos yra duomenų perdavimo objektai jūsų API. Šiuo metu vartotojo sąsajoje nėra jokių jų savybių.
Norėdami deklaruoti jų savybes vartotojo sąsajoje, tiesiog pridėkite dekoratorių. Komentuokite kiekvieną reikalingą ypatybę su @ApiProperty dekoratorius. Komentuokite pasirenkamas ypatybes naudodami @ApiPropertyOptional dekoratorius.
Pavyzdžiui:
// create-demo.dto.ts
importuoti { ApiProperty, ApiPropertyOptional } iš '@nestjs/swagger';
eksportuotiklasė CreateDemoDto {
@ApiProperty({
tipo: Styga,
aprašymas: „Tai būtina nuosavybė“,
})
nuosavybė: styga;
@ApiPropertyOptional({
tipo: Styga,
aprašymas: „Tai neprivaloma nuosavybė“,
})
neprivaloma nuosavybė: styga;
}
@ApiProperty ir @ApiPropertyOptional dekoratoriai priima parinkčių objektą. Tas objektas apibūdina toliau pateiktą savybę.
Atminkite, kad parinkčių objektas naudoja „JavaScript“, o ne „TypeScript“. Taigi JavaScript tipo deklaracijos (ty String, o ne eilutė).
Anotuojant duomenų perdavimo objekto ypatybes, laukiamų duomenų pavyzdys įtraukiamas į skiltį Schemos. Jis taip pat atnaujina susietą HTTP maršrutą pateikdamas laukiamų duomenų pavyzdį.
5 veiksmas: nustatykite API atsakymus
Savo valdiklio klasėje naudokite @ApiResponse dekoratoriai, kad dokumentuotų visus galimus kiekvieno HTTP maršruto atsakymus. Skirtingi @ApiResponse dekoratoriai nurodo kiekvieno galutinio taško atsakymų tipą.
Mes paaiškinome bendri HTTP atsakymai, jei nežinote, ką jie reiškia.
@ApiResponse dekoratoriai priima pasirenkamą objektą, apibūdinantį atsakymą.
Įprasti POST atsakymai
Į POST užklausą galimi atsakymai:
- ApiCreatedResponse, už sėkmingą 201 sukurtą atsakymą.
- ApiUnprocessableEnityResponse, dėl nepavykusių 422 neapdorojamų objektų atsakymų.
- ApiForbiddenResponse, už 403 draudžiamus atsakymus.
Pavyzdžiui:
// demo.controller.ts
@Įrašas()
@ApiCreatedResponse({ description: „Sukurta sėkmingai“ })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
@ApiForbiddenResponse({ description: „Neteisėta užklausa“ })
sukurti (@Kūnas() createDemoDto: CreateDemoDto) {
grąžintitai.demoService.create (createDemoDto);
}
Įprasti GET atsakymai
Į GET užklausas galimi atsakymai:
- ApiOkResponse, už 200 gerai atsakymų.
- ApiForbiddenResponse, už 403 draudžiamus atsakymus.
- ApiNotFoundResponse, už 404 nerastas atsakymus.
Pavyzdžiui:
// demo.controller.ts
@Gauti()
@ApiOkResponse({ description: „Ištekliai sėkmingai grąžinti“ })
@ApiForbiddenResponse({ description: „Neteisėta užklausa“ })
rasti viską() {
grąžintitai.demoService.findAll();
}
@Gauti(':id')
@ApiOkResponse({ description: „Išteklius sėkmingai grąžintas“ })
@ApiForbiddenResponse({ description: „Neteisėta užklausa“ })
@ApiNotFoundResponse({ aprašymas: 'Išteklius nerastas' })
rasti vieną (@Param('aš padariau: styga) {
grąžintitai.demoService.findOne(+id);
}
Įprasti PATCH ir UPDATE atsakymai
Į PATCH ir UPDATE užklausas galimi atsakymai:
- ApiOkResponse, už 200 gerai atsakymų.
- ApiNotFoundResponse, už 404 nerastas atsakymus.
- ApiUnprocessibleEntityResponse, dėl nepavykusių 422 neapdorojamų objektų atsakymų.
- ApiForbiddenResponse, už 403 draudžiamus atsakymus.
Pavyzdžiui:
// demo.controller.ts
@Patch(':id')
@ApiOkResponse({ description: 'Išteklius sėkmingai atnaujintas' })
@ApiNotFoundResponse({ aprašymas: 'Išteklius nerastas' })
@ApiForbiddenResponse({ description: „Neteisėta užklausa“ })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
atnaujinti (@Param('aš padariau: styga, @Kūnas() updateDemoDto: UpdateDemoDto) {
grąžintitai.demoService.update(+id, updateDemoDto);
}
Įprasti DELETE atsakymai
Į DELETE užklausas galimi atsakymai:
- ApiOkResponse, už 200 gerai atsakymų.
- ApiForbiddenResponse, už 403 draudžiamus atsakymus.
- ApiNotFoundResponse, už 404 nerastas atsakymus.
Pavyzdžiui:
// demo.controller.ts
@Ištrinti(':id')
@ApiOkResponse({ description: „Išteklius sėkmingai grąžintas“ })
@ApiForbiddenResponse({ description: „Neteisėta užklausa“ })
@ApiNotFoundResponse({ aprašymas: 'Išteklius nerastas' })
pašalinti (@Param('aš padariau: styga) {
grąžintitai.demoService.remove(+id);
}
Šie dekoratoriai užpildo jūsų dokumentus galimais atsakymais. Juos galite peržiūrėti naudodami išskleidžiamąjį meniu šalia kiekvieno maršruto.
Jūsų dokumentacijos peržiūra
Kai sąranka bus baigta, dokumentaciją galėsite peržiūrėti localhost:
Pagrindiniai Swagger API dokumentacijos dalykai yra aprašymas, atsakymų tipai ir schemos apibrėžimas. Tai yra pagrindiniai dalykai, kurių reikia norint sukurti gerą API dokumentaciją.