Swagger je bezplatný open-source rámec pro vytváření interaktivní a uživatelsky přívětivé dokumentace API. Generuje interaktivní webové stránky, které vám umožňují testovat API s různými vstupy.
Swagger podporuje datovou část JSON i XML. Dokumentace, kterou generuje, je vhodná pro vývojáře i nevývojáře.
Svá webová rozhraní API NestJS můžete dokumentovat prostřednictvím Swagger pomocí jednoduchých dekorátorů, aniž byste museli opustit své IDE.
Krok 1: Generování API
Než začnete, musíte vytvořit demo API, které Swagger vygeneruje dokumentaci.
Demo API vygenerujete od začátku pomocí NestJS CLI.
Nejprve vygenerujte nový projekt NestJS spuštěním:
hnízdo nové <název-vašeho-projektu>
Poté změňte adresář na již vytvořený projekt spuštěním:
CD <název-vašeho-projektu>
Dále vygenerujete REST API s CLI spuštěním:
nest generovat zdroj demo --no-spec
Zobrazí se dotaz „Jakou transportní vrstvu používáte?“ vybrat REST API.
Uvidíte další dotaz s dotazem: „Chcete vygenerovat vstupní body CRUD?“ Typ Y a udeřit Vstupte.
Výše uvedený příkaz generuje plně funkční REST API s koncovými body CRUD a bez souborů testů jednotek. Proto, --no-spec příznak v příkazu výše.
Krok 2: Nainstalujte Swagger
Nainstalujte Swagger a jeho knihovnu Express UI spuštěním:
npm Nainstalujte--save @nestjs/swagger swagger-ui-express
Krok 3: Nakonfigurujte Swagger
Ve vašem main.ts soubor, import SwaggerModule a DocumentBuilder z @nestjs/swagger.
DocumentBuilder pomáhá při strukturování základního dokumentu. Poskytuje několik metod, které můžete spojit a uzavřít pomocí stavět metoda.
Tyto metody umožňují konfiguraci mnoha atributů, jako je název, popis a verze.
Vytvořit config objektová proměnná ve vašem bootstrap fungovat takto:
konst config = Nový DocumentBuilder()
.setTitle('Demo API')
.setDescription('Ukázkové rozhraní API s Funkce CRUD')
.setVersion('1.0')
.stavět();
Nová instance DocumentBuilder vytvoří základní dokument, který odpovídá Specifikace OpenAPI. Tuto instanci pak můžete použít k nastavení názvu, popisu a verze pomocí příslušných metod.
Dále budete muset vytvořit úplný dokument se všemi trasami HTTP definovanými pomocí základního dokumentu.
Chcete-li to provést, zavolejte na vytvořitDokument metoda na SwaggerModule. createDocument přijímá dva argumenty: instanci aplikace a objekt možností Swagger. Uložte výsledek tohoto volání do proměnné pro pozdější použití:
konstdokument = SwaggerModule.createDocument (aplikace, konfigurace);
Dále zavolejte na založit metoda na SwaggerModule. Metoda nastavení má tři argumenty:
- Cesta uživatelského rozhraní Swagger. Podle konvence můžete použít „api“.
- Instance aplikace
- Celý dokument
Metoda nastavení navíc přebírá volitelné možnosti objektu. Vidět Dokumentace NestJS o možnostech dokumentu Swagger abyste se o tom dozvěděli více.
Jako tak:
SwaggerModule.setup('api', aplikace, dokument);
Spusťte aplikaci a přejděte na http://localhost:
Na stránce byste měli vidět uživatelské rozhraní Swagger.
Obrázek výše je výchozí zobrazení uživatelského rozhraní Swagger se všemi cestami HTTP ve vašem řadiči definovanými. Budete si ho muset přizpůsobit tak, aby vyhovoval vašim funkcím API.
Krok 4: Přizpůsobte vlastnosti API
Ve výchozím nastavení přidává Swagger před celou sekci HTTP trasy záhlaví, které zní „výchozí“. Můžete to změnit tak, že svou třídu řadiče označíte pomocí @ApiTags dekoratér a předání preferované značky jako argumentu.
Jako tak:
// demo.controller.ts
import { ApiTags } z '@nestjs/swagger';
@ApiTags('Ukázka')
@Ovladač('demo')
vývoznítřída DemoController {
Sekce Schemas obsahuje objekty přenosu dat ve vašem rozhraní API. V současné době uživatelské rozhraní neobsahuje žádnou z jejich vlastností.
Chcete-li deklarovat jejich vlastnosti v uživatelském rozhraní, jednoduše přidejte dekorátory. Označte každou požadovanou vlastnost pomocí @ApiProperty dekoratér. Označte volitelné vlastnosti pomocí @ApiPropertyOptional dekoratér.
Například:
// create-demo.dto.ts
import { ApiProperty, ApiPropertyOptional } z '@nestjs/swagger';
vývoznítřída CreateDemoDto {
@ApiProperty({
typ: Tětiva,
popis: 'Toto je povinná vlastnost',
})
vlastnictví: tětiva;
@ApiPropertyOptional({
typ: Tětiva,
popis: 'Toto je volitelná vlastnost',
})
volitelná vlastnost: tětiva;
}
Dekorátory @ApiProperty a @ApiPropertyOptional přijímají každý objekt options. Tento objekt popisuje vlastnost, která následuje níže.
Všimněte si, že objekt options používá JavaScript, nikoli TypeScript. Proto deklarace typu JavaScript (tj. řetězec, nikoli řetězec).
Anotace vlastností objektu Data-transfer přidá příklad očekávaných dat do sekce Schémata. Aktualizuje také přidruženou trasu HTTP příkladem očekávaných dat.
Krok 5: Nastavte odpovědi API
Ve své třídě ovladačů použijte @ApiResponse dekorátory pro dokumentaci všech potenciálních odpovědí pro každou cestu HTTP. Pro každý koncový bod popisují různé dekorátory @ApiResponse typ očekávaných odpovědí.
Vysvětlili jsme běžné HTTP odpovědi, v případě, že nevíte, co znamenají.
Dekorátory @ApiResponse přijímají volitelný objekt, který popisuje odpověď.
Běžné odpovědi POST
U požadavku POST mezi pravděpodobné odpovědi patří:
- ApiCreatedResponse, za úspěšných 201 vytvořených odpovědí.
- ApiUnprocessableEnityResponse, za neúspěšných 422 nezpracovatelných odpovědí entity.
- ApiForbiddenResponse, za 403 zakázaných odpovědí.
Například:
// demo.controller.ts
@Pošta()
@ApiCreatedResponse({ description: 'Úspěšně vytvořeno' })
@ApiUnprocessableEntityResponse({ description: 'Špatný požadavek' })
@ApiForbiddenResponse({ description: 'Neautorizovaný požadavek' })
vytvořit(@Tělo() createDemoDto: CreateDemoDto) {
vrátit setento.demoService.create (createDemoDto);
}
Běžné odpovědi GET
U požadavků GET patří mezi pravděpodobné odpovědi:
- ApiOkResponse, za 200 ok odpovědí.
- ApiForbiddenResponse, za 403 zakázaných odpovědí.
- ApiNotFoundResponse, pro 404 nenalezených odpovědí.
Například:
// demo.controller.ts
@Dostat()
@ApiOkResponse({ description: 'Prostředky byly úspěšně vráceny' })
@ApiForbiddenResponse({ description: 'Neautorizovaný požadavek' })
findAll() {
vrátit setento.demoService.findAll();
}
@Dostat(':id')
@ApiOkResponse({ description: 'Zdroj byl úspěšně vrácen' })
@ApiForbiddenResponse({ description: 'Neautorizovaný požadavek' })
@ApiNotFoundResponse({ description: 'Zdroj nenalezen' })
Najdi jednu(@Param('udělal jsem: tětiva) {
vrátit setento.demoService.findOne(+id);
}
Společné odpovědi PATCH a UPDATE
U požadavků PATCH a UPDATE mezi pravděpodobné odpovědi patří:
- ApiOkResponse, za 200 ok odpovědí.
- ApiNotFoundResponse, pro 404 nenalezených odpovědí.
- ApiUnprocessibleEntityResponse, za neúspěšných 422 nezpracovatelných odpovědí entity.
- ApiForbiddenResponse, za 403 zakázaných odpovědí.
Například:
// demo.controller.ts
@Náplast(':id')
@ApiOkResponse({ description: 'Zdroj byl úspěšně aktualizován' })
@ApiNotFoundResponse({ description: 'Zdroj nenalezen' })
@ApiForbiddenResponse({ description: 'Neautorizovaný požadavek' })
@ApiUnprocessableEntityResponse({ description: 'Špatný požadavek' })
Aktualizace(@Param('udělal jsem: tětiva, @Tělo() updateDemoDto: UpdateDemoDto) {
vrátit setento.demoService.update(+id, updateDemoDto);
}
Běžné odpovědi DELETE
U požadavků DELETE patří mezi pravděpodobné odpovědi:
- ApiOkResponse, za 200 ok odpovědí.
- ApiForbiddenResponse, za 403 zakázaných odpovědí.
- ApiNotFoundResponse, pro 404 nenalezených odpovědí.
Například:
// demo.controller.ts
@Vymazat(':id')
@ApiOkResponse({ description: 'Zdroj byl úspěšně vrácen' })
@ApiForbiddenResponse({ description: 'Neautorizovaný požadavek' })
@ApiNotFoundResponse({ description: 'Zdroj nenalezen' })
odstranit(@Param('udělal jsem: tětiva) {
vrátit setento.demoService.remove(+id);
}
Tito dekoratéři naplní vaši dokumentaci možnými odpověďmi. Můžete je zobrazit pomocí rozbalovací nabídky vedle každé trasy.
Prohlížení vaší dokumentace
Po dokončení nastavení můžete zobrazit dokumentaci na localhost:
Základy dokumentace Swagger API jsou popis, typy odpovědí a definice schématu. Toto jsou základní věci potřebné k vytvoření dobré dokumentace API.