Swagger to bezpłatna platforma typu open source do tworzenia interaktywnej i przyjaznej dla użytkownika dokumentacji interfejsu API. Generuje interaktywne strony internetowe, które umożliwiają testowanie interfejsu API z różnymi danymi wejściowymi.

Swagger obsługuje ładunki JSON i XML. Generowana przez niego dokumentacja jest odpowiednia dla programistów i osób niebędących programistami.

Możesz dokumentować swoje internetowe interfejsy API NestJS za pomocą Swaggera za pomocą prostych dekoratorów, bez konieczności opuszczania IDE.

Krok 1: Generowanie API

Przed rozpoczęciem musisz utworzyć demo API, które Swagger wygeneruje swoją dokumentację.

Demo API wygenerujesz od podstaw za pomocą NestJS CLI.

Najpierw wygeneruj nowy projekt NestJS, uruchamiając:

gniazdo nowe <nazwa-twojego-projektu>

Następnie zmień katalog na już utworzony projekt, uruchamiając:

płyta CD <nazwa-twojego-projektu>

Następnie wygenerujesz REST API z CLI, uruchamiając:

gniazdo wygeneruj demo zasobów --no-spec

Zobaczysz zapytanie z pytaniem „Jakiej warstwy transportowej używasz?” Wybierz REST API.

instagram viewer

Zobaczysz kolejne zapytanie z pytaniem „Czy chcesz wygenerować punkty wejścia CRUD?” Rodzaj Tak i uderzył Wchodzić.

Powyższe polecenie generuje w pełni funkcjonalne REST API z punktami końcowymi CRUD i bez plików testów jednostkowych. Stąd --no-spec w powyższym poleceniu.

Krok 2: Zainstaluj Swagger

Zainstaluj Swagger i jego bibliotekę Express UI, uruchamiając:

npm zainstalować--save @nestjs/swagger swagger-ui-express

Krok 3: Skonfiguruj Swagger

W Twoim main.ts plik, import Moduł Swagger oraz Kreator dokumentów z @nestjs/swagger.

DocumentBuilder pomaga w konstruowaniu dokumentu bazowego. Zapewnia kilka metod, które można połączyć ze sobą i zamknąć za pomocą budować metoda.

Te metody umożliwiają konfigurację wielu atrybutów, takich jak tytuł, opis i wersja.

Stwórz konfiguracja zmienna obiektu w twoim bootstrap funkcjonować tak:

stały konfiguracja = Nowy Kreator Dokumentów()
 .setTitle('Demo API')
 .setDescription('Demonstracyjny interfejs API z Funkcjonalność CRUD")
 .setWersja('1.0')
 .budować();

Nowa instancja DocumentBuilder tworzy dokument bazowy, który pasuje do Specyfikacja OpenAPI. Możesz następnie użyć tego wystąpienia, aby ustawić tytuł, opis i wersję za pomocą odpowiednich metod.

Następnie musisz utworzyć kompletny dokument ze wszystkimi trasami HTTP zdefiniowanymi przy użyciu dokumentu podstawowego.

Aby to zrobić, zadzwoń do utwórz dokument metoda na SwaggerModule. createDocument przyjmuje dwa argumenty: instancję aplikacji i obiekt opcji Swagger. Przechowuj wynik tego wywołania w zmiennej do późniejszego wykorzystania:

stałydokument = SwaggerModule.createDocument (aplikacja, konfiguracja);

Następnie zadzwoń do organizować coś metoda na SwaggerModule. Metoda setup przyjmuje trzy argumenty:

  1. Ścieżka interfejsu Swagger. Zgodnie z konwencją możesz użyć „api”.
  2. Instancja aplikacji
  3. Pełny dokument

Ponadto metoda instalacji przyjmuje opcjonalny obiekt opcji. Widzieć Dokumentacja NestJS dotycząca opcji dokumentów Swagger aby dowiedzieć się więcej na ten temat.

Tak jak:

SwaggerModule.setup('api', aplikacja, dokument);

Uruchom aplikację i przejdź do http://localhost:/api

Powinieneś zobaczyć interfejs Swagger wyświetlony na stronie.

Powyższy obrazek to domyślny widok interfejsu użytkownika Swagger ze zdefiniowanymi wszystkimi trasami HTTP w kontrolerze. Musisz go dostosować, aby pasował do funkcjonalności interfejsu API.

Krok 4: Dostosuj właściwości API

Domyślnie Swagger poprzedza całą sekcję trasy HTTP nagłówkiem, który brzmi „domyślnie”. Możesz to zmienić, dodając adnotację do swojej klasy kontrolera za pomocą @ApiTags dekorator i przekazanie preferowanego tagu jako argumentu.

Tak jak:

// demo.kontroler.ts
import { tagi API } z '@nestjs/swagger';
@ApiTags('Próbny')
@Kontroler('próbny')
eksportklasa DemoKontroler {

Sekcja Schematy zawiera obiekty przenoszenia danych w Twoim interfejsie API. Obecnie interfejs użytkownika nie zawiera żadnej z ich właściwości.

Aby zadeklarować ich właściwości w interfejsie użytkownika, po prostu dodaj dekoratory. Dodaj adnotację do każdej wymaganej właściwości za pomocą @ApiProperty dekorator. Opisz opcjonalne właściwości za pomocą @ApiPropertyOpcjonalne dekorator.

Na przykład:

// utwórz-demo.dto.ts
import { Usługa Api, Usługa ApiOpcjonalna } z '@nestjs/swagger';
eksportklasa UtwórzDemoDto {
@ApiProperty({
rodzaj: Strunowy,
 opis: 'To jest wymagana właściwość',
 })
 własność: strunowy;
@ApiPropertyOpcjonalne({
rodzaj: Strunowy,
 opis: 'To jest właściwość opcjonalna',
 })
 opcjonalnieNieruchomość: strunowy;
}

Dekoratory @ApiProperty i @ApiPropertyOptional akceptują obiekt opcji. Ten obiekt opisuje właściwość, która następuje poniżej.

Zwróć uwagę, że obiekt options używa JavaScript, a nie TypeScript. Stąd deklaracje typu JavaScript (tj. String, a nie string).

Adnotacja właściwości obiektu transferu danych dodaje przykład oczekiwanych danych do sekcji Schematy. Aktualizuje również powiązaną trasę HTTP o przykład oczekiwanych danych.

Krok 5: Ustaw odpowiedzi API

W swojej klasie kontrolera użyj @ApiResponse dekoratory do dokumentowania wszystkich potencjalnych odpowiedzi dla każdej trasy HTTP. Dla każdego punktu końcowego różne dekoratory @ApiResponse opisują typ oczekiwanych odpowiedzi.

Wyjaśniliśmy typowe odpowiedzi HTTP, jeśli nie wiesz, co one oznaczają.

Dekoratory @ApiResponse akceptują opcjonalny obiekt opisujący odpowiedź.

Wspólne odpowiedzi POST

W przypadku żądania POST prawdopodobne odpowiedzi obejmują:

  • ApiCreatedResponse, za udane 201 utworzonych odpowiedzi.
  • Odpowiedź API UnprocessableEnity, dla nieudanych 422 odpowiedzi niemożliwych do przetworzenia.
  • ApiZabroniona odpowiedź, dla 403 zabronionych odpowiedzi.

Na przykład:

// demo.kontroler.ts
@Poczta()
@ApiCreatedResponse({ opis: „Utworzono pomyślnie”})
@ApiUnprocessableEntityResponse({ opis: „Złe żądanie” })
@ApiForbiddenResponse({ opis: 'Nieautoryzowane żądanie' })
 Stwórz(@Ciało() createDemoDto: CreateDemoDto) {
zwrócićten.demoService.create (createDemoDto);
 }

Wspólne odpowiedzi GET

W przypadku żądań GET prawdopodobne odpowiedzi obejmują:

  • ApiOkOdpowiedź, dla 200 ok odpowiedzi.
  • ApiZabroniona odpowiedź, dla 403 zabronionych odpowiedzi.
  • ApiNotFoundOdpowiedź, dla 404 nieznalezionych odpowiedzi.

Na przykład:

// demo.kontroler.ts
@Dostać()
@ApiOkResponse({ opis: 'Zasoby zostały zwrócone pomyślnie' })
@ApiForbiddenResponse({ opis: 'Nieautoryzowane żądanie' })
 Znajdź wszystko() {
zwrócićten.demoService.findAll();
 }
@Dostać(':ID')
@ApiOkResponse({ opis: 'Zasób został zwrócony pomyślnie' })
@ApiForbiddenResponse({ opis: 'Nieautoryzowane żądanie' })
@ApiNotFoundResponse({ opis: 'Nie znaleziono zasobu' })
 znajdźJeden(@Param('Zrobiłem: strunowy) {
zwrócićten.demoService.findOne(+id);
 }

Wspólne odpowiedzi na poprawki i aktualizacje

W przypadku żądań PATCH i UPDATE prawdopodobne odpowiedzi obejmują:

  • ApiOkOdpowiedź, dla 200 ok odpowiedzi.
  • ApiNotFoundOdpowiedź, dla 404 nieznalezionych odpowiedzi.
  • ApiNieprzetwarzalnyEntityReakcja, dla nieudanych 422 odpowiedzi niemożliwych do przetworzenia.
  • ApiZabroniona odpowiedź, dla 403 zabronionych odpowiedzi.

Na przykład:

// demo.kontroler.ts
@Łata(':ID')
@ApiOkResponse({ opis: 'Zasób został zaktualizowany pomyślnie' })
@ApiNotFoundResponse({ opis: 'Nie znaleziono zasobu' })
@ApiForbiddenResponse({ opis: 'Nieautoryzowane żądanie' })
@ApiUnprocessableEntityResponse({ opis: „Złe żądanie” })
 aktualizacja(@Param('Zrobiłem: strunowy, @Ciało() updateDemoDto: UpdateDemoDto) {
zwrócićten.demoService.update(+id, updateDemoDto);
 }

Wspólne odpowiedzi DELETE

W przypadku żądań DELETE prawdopodobne odpowiedzi obejmują:

  • ApiOkOdpowiedź, dla 200 ok odpowiedzi.
  • ApiZabroniona odpowiedź, dla 403 zabronionych odpowiedzi.
  • ApiNotFoundOdpowiedź, dla 404 nieznalezionych odpowiedzi.

Na przykład:

// demo.kontroler.ts
@Usuwać(':ID')
@ApiOkResponse({ opis: 'Zasób został zwrócony pomyślnie' })
@ApiForbiddenResponse({ opis: 'Nieautoryzowane żądanie' })
@ApiNotFoundResponse({ opis: 'Nie znaleziono zasobu' })
 usunąć(@Param('Zrobiłem: strunowy) {
zwrócićten.demoService.remove(+id);
 }

Te dekoratory wypełniają dokumentację możliwymi odpowiedziami. Możesz je wyświetlić, korzystając z rozwijanego menu obok każdej trasy.

Przeglądanie dokumentacji

Po zakończeniu konfiguracji możesz wyświetlić dokumentację na Lokalny Gospodarz:/api. Powinien wywołać twoją interaktywną dokumentację API.

Podstawowymi elementami dokumentacji interfejsu Swagger API są opis, typy odpowiedzi i definicja schematu. To są podstawowe rzeczy potrzebne do stworzenia dobrej dokumentacji API.