Swagger je bezplatný open-source rámec na vytváranie interaktívnej a užívateľsky prívetivej dokumentácie API. Vytvára interaktívne webové stránky, ktoré vám umožňujú testovať API s rôznymi vstupmi.

Swagger podporuje užitočné zaťaženie JSON aj XML. Dokumentácia, ktorú generuje, je vhodná pre vývojárov aj nevývojárov.

Svoje webové rozhrania API NestJS môžete zdokumentovať cez Swagger pomocou jednoduchých dekorátorov bez toho, aby ste museli opustiť svoje IDE.

Krok 1: Generovanie API

Pred spustením musíte vytvoriť demo API, ktoré Swagger vygeneruje dokumentáciu.

Demo API vygenerujete od začiatku pomocou NestJS CLI.

Najprv vygenerujte nový projekt NestJS spustením:

hniezdo nové <názov-vášho-projektu>

Potom zmeňte adresár na už vytvorený projekt spustením:

cd <názov-vášho-projektu>

Ďalej vygenerujete REST API s CLI spustením:

demo generovanie zdrojov --bez špecifikácie

Zobrazí sa otázka „Akú transportnú vrstvu používate?“ vyberte REST API.

Uvidíte ďalší dotaz s otázkou: „Chceli by ste vygenerovať vstupné body CRUD?“ Typ Y a zasiahnuť Zadajte.

instagram viewer

Vyššie uvedený príkaz generuje plne funkčné REST API s koncovými bodmi CRUD a bez súborov testovania jednotiek. Preto, --bez špecifikácie príznak v príkaze vyššie.

Krok 2: Nainštalujte Swagger

Nainštalujte Swagger a jeho knižnicu Express UI spustením:

npm Inštalácia--save @nestjs/swagger swagger-ui-express

Krok 3: Nakonfigurujte Swagger

V tvojom main.ts súbor, import SwaggerModule a DocumentBuilder od @nestjs/swagger.

DocumentBuilder pomáha pri štruktúrovaní základného dokumentu. Poskytuje niekoľko metód, ktoré môžete spojiť a uzavrieť stavať metóda.

Tieto metódy umožňujú konfiguráciu mnohých atribútov, ako je názov, popis a verzia.

Vytvor config objektová premenná vo vašom bootstrap fungovať takto:

konšt config = Nový DocumentBuilder()
 .setTitle('Demo API')
 .setDescription('Ukážkové rozhranie API s Funkcia CRUD')
 .setVersion('1.0')
 .build();

Nová inštancia DocumentBuilder vytvorí základný dokument, ktorý sa zhoduje s Špecifikácia OpenAPI. Túto inštanciu potom môžete použiť na nastavenie názvu, popisu a verzie pomocou príslušných metód.

Ďalej budete musieť vytvoriť úplný dokument so všetkými trasami HTTP definovanými pomocou základného dokumentu.

Ak to chcete urobiť, zavolajte na vytvoriť dokument metóda na SwaggerModule. createDocument akceptuje dva argumenty: inštanciu aplikácie a objekt možností Swagger. Uložte výsledok tohto volania do premennej pre neskoršie použitie:

konštdokument = SwaggerModule.createDocument (aplikácia, konfigurácia);

Ďalej zavolajte na nastaviť metóda na SwaggerModule. Metóda nastavenia obsahuje tri argumenty:

  1. Cesta používateľského rozhrania Swagger. Podľa konvencie môžete použiť „api“.
  2. Inštancia aplikácie
  3. Celý dokument

Okrem toho metóda nastavenia používa voliteľný objekt volieb. Pozri Dokumentácia NestJS o možnostiach dokumentu Swagger aby ste sa o tom dozvedeli viac.

Ako:

SwaggerModule.setup('api', aplikácia, dokument);

Spustite aplikáciu a prejdite na http://localhost:/api

Na stránke by ste mali vidieť používateľské rozhranie Swagger.

Obrázok vyššie je predvoleným zobrazením používateľského rozhrania Swagger so všetkými cestami HTTP vo vašom ovládači. Budete ho musieť prispôsobiť tak, aby vyhovoval vašim funkciám API.

Krok 4: Prispôsobte vlastnosti API

V predvolenom nastavení Swagger predpíše celú časť trasy HTTP hlavičkou, ktorá znie „predvolené“. Môžete to zmeniť tak, že svoju triedu ovládača označíte symbolom @ApiTags dekoratér a odovzdanie preferovanej značky ako argumentu.

Ako:

// demo.controller.ts
importovať { ApiTags } od '@nestjs/swagger';
@ApiTags("Ukážka")
@Controller('demo')
exporttrieda DemoController {

Časť Schemas obsahuje objekty prenosu údajov vo vašom rozhraní API. V súčasnosti používateľské rozhranie neobsahuje žiadnu z ich vlastností.

Ak chcete deklarovať ich vlastnosti v používateľskom rozhraní, jednoducho pridajte dekorátory. Každú požadovanú vlastnosť označte symbolom @ApiProperty dekoratér. Označte voliteľné vlastnosti pomocou @ApiPropertyOptional dekoratér.

Napríklad:

// create-demo.dto.ts
importovať { ApiProperty, ApiPropertyOptional } od '@nestjs/swagger';
exporttrieda CreateDemoDto {
@ApiProperty({
typu: Reťazec,
 popis: 'Toto je povinná vlastnosť',
 })
 nehnuteľnosť: reťazec;
@ApiPropertyOptional({
typu: Reťazec,
 popis: 'Toto je voliteľná vlastnosť',
 })
 voliteľná vlastnosť: reťazec;
}

Každý z dekorátorov @ApiProperty a @ApiPropertyOptional akceptuje objekt volieb. Tento objekt popisuje vlastnosť, ktorá nasleduje nižšie.

Všimnite si, že objekt options používa JavaScript, nie TypeScript. Preto deklarácie typu JavaScript (t. j. reťazec, nie reťazec).

Anotovanie vlastností objektu prenosu údajov pridá príklad očakávaných údajov do sekcie Schemas. Aktualizuje tiež súvisiacu trasu HTTP s príkladom očakávaných údajov.

Krok 5: Nastavte odpovede API

Vo svojej triede ovládačov použite @ApiResponse dekorátorov na zdokumentovanie všetkých potenciálnych odpovedí pre každú HTTP trasu. Pre každý koncový bod popisujú rôzne dekorátory @ApiResponse typ očakávaných odpovedí.

Vysvetlili sme bežné odpovede HTTP, v prípade, že neviete, čo znamenajú.

Dekorátory @ApiResponse akceptujú voliteľný objekt, ktorý popisuje odpoveď.

Bežné odpovede POST

V prípade požiadavky POST pravdepodobné odpovede zahŕňajú:

  • ApiCreatedResponse, za úspešných 201 vytvorených odpovedí.
  • ApiUnprocessableEnityResponse, za neúspešných 422 nespracovateľných odpovedí entity.
  • ApiForbiddenResponse, za 403 zakázaných odpovedí.

Napríklad:

// demo.controller.ts
@Príspevok()
@ApiCreatedResponse({ description: 'Úspešne vytvorené' })
@ApiUnprocessableEntityResponse({ description: 'Zlá požiadavka' })
@ApiForbiddenResponse({ description: 'Neoprávnená požiadavka' })
 vytvoriť (@Telo() createDemoDto: CreateDemoDto) {
vrátiťtoto.demoService.create (createDemoDto);
 }

Bežné odpovede GET

V prípade žiadostí GET medzi pravdepodobné odpovede patria:

  • ApiOkResponse, za 200 ok odpovedí.
  • ApiForbiddenResponse, za 403 zakázaných odpovedí.
  • ApiNotFoundResponse, pre 404 nenájdených odpovedí.

Napríklad:

// demo.controller.ts
@Získať()
@ApiOkResponse({ description: 'Zdroje boli úspešne vrátené' })
@ApiForbiddenResponse({ description: 'Neoprávnená požiadavka' })
 findAll() {
vrátiťtoto.demoService.findAll();
 }
@Získať(':id')
@ApiOkResponse({ description: 'Zdroj bol úspešne vrátený' })
@ApiForbiddenResponse({ description: 'Neoprávnená požiadavka' })
@ApiNotFoundResponse({ description: 'Resource not found' })
 nájdi jeden(@Param('urobil som: reťazec) {
vrátiťtoto.demoService.findOne(+id);
 }

Bežné odpovede PATCH a UPDATE

V prípade požiadaviek PATCH a UPDATE medzi pravdepodobné odpovede patria:

  • ApiOkResponse, za 200 ok odpovedí.
  • ApiNotFoundResponse, pre 404 nenájdených odpovedí.
  • ApiUnprocessibleEntityResponse, za neúspešných 422 nespracovateľných odpovedí entity.
  • ApiForbiddenResponse, za 403 zakázaných odpovedí.

Napríklad:

// demo.controller.ts
@Patch(':id')
@ApiOkResponse({ description: 'Zdroj bol úspešne aktualizovaný' })
@ApiNotFoundResponse({ description: 'Resource not found' })
@ApiForbiddenResponse({ description: 'Neoprávnená požiadavka' })
@ApiUnprocessableEntityResponse({ description: 'Zlá požiadavka' })
 aktualizovať(@Param('urobil som: reťazec, @Telo() updateDemoDto: UpdateDemoDto) {
vrátiťtoto.demoService.update(+id, updateDemoDto);
 }

Bežné odpovede DELETE

V prípade žiadostí DELETE medzi pravdepodobné odpovede patria:

  • ApiOkResponse, za 200 ok odpovedí.
  • ApiForbiddenResponse, za 403 zakázaných odpovedí.
  • ApiNotFoundResponse, pre 404 nenájdených odpovedí.

Napríklad:

// demo.controller.ts
@Odstrániť(':id')
@ApiOkResponse({ description: 'Zdroj bol úspešne vrátený' })
@ApiForbiddenResponse({ description: 'Neoprávnená požiadavka' })
@ApiNotFoundResponse({ description: 'Resource not found' })
 odstrániť (@Param('urobil som: reťazec) {
vrátiťtoto.demoService.remove(+id);
 }

Títo dekoratéri naplnia vašu dokumentáciu možnými odpoveďami. Môžete ich zobraziť pomocou rozbaľovacej ponuky vedľa každej trasy.

Prezeranie vašej dokumentácie

Po dokončení nastavenia si môžete pozrieť dokumentáciu na localhost:/api. Mal by vyvolať vašu interaktívnu dokumentáciu API.

Základom dokumentácie Swagger API je popis, typy odpovedí a definícia schémy. Toto sú základné veci potrebné na vytvorenie dobrej dokumentácie API.