A Swagger egy ingyenes, nyílt forráskódú keretrendszer interaktív és felhasználóbarát API-dokumentáció létrehozásához. Interaktív weboldalakat hoz létre, amelyek lehetővé teszik egy API tesztelését különböző bemenetekkel.

A Swagger támogatja a JSON- és az XML-adatokat is. Az általa generált dokumentáció fejlesztők és nem fejlesztők számára is használható.

Dokumentálhatja NestJS webes API-jait a Swaggeren keresztül egyszerű dekorátorok segítségével, anélkül, hogy elhagyná az IDE-jét.

1. lépés: Az API létrehozása

Mielőtt elkezdené, létre kell hoznia egy bemutató API-t, amelyhez a Swagger elkészíti a dokumentációját.

A demó API-t a semmiből állíthatja elő a NestJS parancssori felület segítségével.

Először is hozzon létre egy új NestJS projektet a következő futtatásával:

fészek új <a projekt neve>

Ezután módosítsa a könyvtárat a már létrehozott projektre a következő futtatással:

CD <a projekt neve>

Ezután létrehoz egy REST API-t a CLI-vel a következő futtatásával:

nest erőforrás bemutatót generál --no-specifikáció

Megjelenik a következő kérdés: „Milyen szállítási réteget használ?” válassza ki REST API.

Egy másik lekérdezés jelenik meg a következő kérdéssel: "Szeretne CRUD belépési pontokat generálni?" típus Y és ütött Belép.

A fenti parancs generálja egy teljesen működőképes REST API CRUD végpontokkal és az egységteszt fájlok nélkül. Ezért a --no-specifikáció zászlót a fenti parancsban.

2. lépés: Telepítse a Swaggert

Telepítse a Swaggert és annak Express UI könyvtárát a következő futtatással:

npm telepítés--save @nestjs/swagger swagger-ui-express

3. lépés: Konfigurálja a Swaggert

A tiédben fő.ts fájl, import SwaggerModule és DocumentBuilder tól től @nestjs/swagger.

A DocumentBuilder segít az alapdokumentum strukturálásában. Számos módszert kínál, amelyeket összeláncolhat és bezárhat a épít módszer.

Ezek a módszerek számos attribútum, például cím, leírás és verzió konfigurálását teszik lehetővé.

Hozzon létre egy config objektumváltozó a te bootstrap így működik:

const config = új DocumentBuilder()
 .setTitle('Demo API')
 .setDescription('A Demo API val vel CRUD funkció")
 .setVersion('1.0')
 .épít();

A DocumentBuilder új példánya létrehoz egy alapdokumentumot, amely megfelel a OpenAPI specifikáció. Ezután ezt a példányt használhatja a cím, a leírás és a verzió beállítására a megfelelő módszerekkel.

Ezután létre kell hoznia egy teljes dokumentumot az alapdokumentum segítségével meghatározott összes HTTP-útvonallal.

Ehhez hívja a CreateDocument módszer a SwaggerModule-on. A createDocument két argumentumot fogad el: egy alkalmazáspéldányt és egy Swagger beállítások objektumot. Tárolja a hívás eredményét egy változóban későbbi használatra:

constdokumentum = SwaggerModule.createDocument (alkalmazás, konfiguráció);

Ezután hívja a beállít módszer a SwaggerModule-on. A beállítási módszer három argumentumot tartalmaz:

  1. A Swagger UI elérési útja. Megállapodás szerint használhatja az „api”-t.
  2. Egy alkalmazáspéldány
  3. A teljes dokumentum

Ezenkívül a beállítási módszer egy opcionális beállítási objektumot vesz igénybe. Lát A NestJS dokumentációja a Swagger dokumentumbeállításairól hogy többet megtudjon róla.

Például így:

SwaggerModule.setup('api', alkalmazás, dokumentum);

Indítsa el az alkalmazást, és lépjen a címre http://localhost:/api

Látnia kell a Swagger felhasználói felületet az oldalon.

A fenti kép a Swagger felhasználói felület alapértelmezett nézete, a vezérlő összes HTTP-útvonalával definiálva. Testre kell szabnia, hogy illeszkedjen az API funkcióihoz.

4. lépés: Az API tulajdonságainak testreszabása

Alapértelmezés szerint a Swagger a teljes HTTP útvonalszakaszt egy „alapértelmezett” fejléccel látja el. Ezt úgy módosíthatja, hogy a vezérlőosztályát a következővel jelöli meg @ApiTags lakberendezőt, és érvként adja át a kívánt címkét.

Például így:

// demo.controller.ts
import { ApiTags } tól től '@nestjs/swagger';
@ApiTags('Demó')
@Vezérlő('demó')
exportosztály DemoController {

A Sémák szakasz az API adatátviteli objektumait tartalmazza. Jelenleg a felhasználói felület egyik tulajdonságát sem tartalmazza.

Ha deklarálni szeretné tulajdonságaikat a felhasználói felületen, egyszerűen adjon hozzá dekorátorokat. Jelölje meg az egyes szükséges tulajdonságokat a @ApiProperty lakberendező. Az opcionális tulajdonságokat a @ApiPropertyOpcionális lakberendező.

Például:

// create-demo.dto.ts
import { ApiProperty, ApiPropertyOptional } tól től '@nestjs/swagger';
exportosztály CreateDemoDto {
@ApiProperty({
típus: Húr,
 leírás: "Ez egy kötelező tulajdonság",
 })
 ingatlan: húr;
@ApiPropertyOpcionális({
típus: Húr,
 leírás: "Ez egy opcionális tulajdonság",
 })
 opcionálisTulajdonság: húr;
}

Az @ApiProperty és @ApiPropertyOptional dekorátorok mindegyike elfogad egy-egy opcióobjektumot. Ez az objektum az alábbiakban leírt tulajdonságot írja le.

Vegye figyelembe, hogy a beállítások objektum JavaScriptet használ, nem TypeScriptet. Innen származik a JavaScript típusdeklaráció (azaz String, nem karakterlánc).

Az adatátviteli objektum tulajdonságainak megjegyzésével a várt adatok egy példája a Sémák szakaszhoz kerül. A várt adatok példájával frissíti a kapcsolódó HTTP-útvonalat is.

5. lépés: Állítsa be az API-válaszokat

A vezérlő osztályában használja a @ApiResponse dekorátorok, hogy dokumentálják az összes lehetséges választ az egyes HTTP-útvonalakhoz. Az egyes végpontokhoz a különböző @ApiResponse dekorátorok leírják a várható válaszok típusát.

Elmagyaráztuk gyakori HTTP-válaszok, ha nem ismeri, mit jelentenek.

A @ApiResponse dekorátorok elfogadnak egy opcionális objektumot, amely leírja a választ.

Közös POST-válaszok

POST-kérés esetén a valószínű válaszok a következők:

  • ApiCreatedResponse, a sikeres 201 létrehozott válaszokért.
  • ApiUnprocessableEnityResponse, sikertelen 422 feldolgozhatatlan entitásválasz esetén.
  • ApiForbiddenResponse, 403 tiltott válaszért.

Például:

// demo.controller.ts
@Post()
@ApiCreatedResponse({ description: 'Sikeresen létrehozva' })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
@ApiForbiddenResponse({ description: 'jogosulatlan kérés' })
 teremt(@Test() createDemoDto: CreateDemoDto) {
Visszatérésez.demoService.create (createDemoDto);
 }

Gyakori GET-válaszok

A GET-kérések esetében a valószínű válaszok a következők:

  • ApiOkResponse, 200 ok válaszért.
  • ApiForbiddenResponse, 403 tiltott válaszért.
  • ApiNotFoundResponse, 404 nem található válasz esetén.

Például:

// demo.controller.ts
@Kap()
@ApiOkResponse({ description: 'Az erőforrásokat sikeresen visszaküldtük' })
@ApiForbiddenResponse({ description: 'jogosulatlan kérés' })
 Találd meg mindet() {
Visszatérésez.demoService.findAll();
 }
@Kap(':id')
@ApiOkResponse({ description: 'Az erőforrást sikeresen visszaküldtük' })
@ApiForbiddenResponse({ description: 'jogosulatlan kérés' })
@ApiNotFoundResponse({ description: 'Az erőforrás nem található' })
 találj egyet(@Param('én csináltam: húr) {
Visszatérésez.demoService.findOne(+id);
 }

Gyakori PATCH és UPDATE válaszok

PATCH és UPDATE kérések esetén a valószínű válaszok a következők:

  • ApiOkResponse, 200 ok válaszért.
  • ApiNotFoundResponse, 404 nem található válasz esetén.
  • ApiUnprocessibleEntityResponse, sikertelen 422 feldolgozhatatlan entitásválasz esetén.
  • ApiForbiddenResponse, 403 tiltott válaszért.

Például:

// demo.controller.ts
@Tapasz(':id')
@ApiOkResponse({ description: 'Az erőforrás sikeresen frissült' })
@ApiNotFoundResponse({ description: 'Az erőforrás nem található' })
@ApiForbiddenResponse({ description: 'jogosulatlan kérés' })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
 frissítés(@Param('én csináltam: húr, @Test() updateDemoDto: UpdateDemoDto) {
Visszatérésez.demoService.update(+id, updateDemoDto);
 }

Gyakori DELETE válaszok

A DELETE kérések esetében a valószínű válaszok a következők:

  • ApiOkResponse, 200 ok válaszért.
  • ApiForbiddenResponse, 403 tiltott válaszért.
  • ApiNotFoundResponse, 404 nem található válasz esetén.

Például:

// demo.controller.ts
@Töröl(':id')
@ApiOkResponse({ description: 'Az erőforrást sikeresen visszaküldtük' })
@ApiForbiddenResponse({ description: 'jogosulatlan kérés' })
@ApiNotFoundResponse({ description: 'Az erőforrás nem található' })
 Remove(@Param('én csináltam: húr) {
Visszatérésez.demoService.remove(+id);
 }

Ezek a lakberendezők feltöltik a dokumentációt a lehetséges válaszokkal. Megtekintheti őket az egyes útvonalak melletti legördülő menüben.

A dokumentáció megtekintése

Ha a beállítás befejeződött, megtekintheti a dokumentációt helyi kiszolgáló:/api. Meg kell jelennie az interaktív API dokumentációjában.

A Swagger API dokumentációjának alapvető elemei a leírás, a választípusok és a séma meghatározása. Ezek az alapvető dolgok, amelyek szükségesek a jó API-dokumentáció elkészítéséhez.