Kroniki Imperium: Wprowadzenie do dokumentacji API

Salve, kronikarzu Imperium! Witaj w jednej z najważniejszych misji naszego Imperium - tworzeniu Kronik API. Tak jak starożytni Rzymianie skrupulatnie dokumentowali swoje prawa, dekrety cesarskie i organizację legionów w Annałach Imperium, tak my będziemy dokumentować nasze API za pomocą Swagger i OpenAPI.

Czym jest OpenAPI?

OpenAPI (dawniej znana jako Swagger Specification) to standardowa specyfikacja do opisywania interfejsów REST API. Wyobraź sobie ją jako oficjalny język urzędowy Imperium - jednolity sposób komunikacji pomiędzy prowincjami.

Specyfikacja OpenAPI definiuje strukturę API w formacie JSON lub YAML:

1// Tak wygląda opis endpointu w formacie OpenAPI
2{
3  "paths": {
4    "/legiones": {
5      "get": {
6        "summary": "Pobierz listę legionów",
7        "description": "Zwraca wszystkie legiony Imperium",
8        "responses": {
9          "200": {
10            "description": "Lista legionów"
11          }
12        }
13      }
14    }
15  }
16}

Czym jest Swagger?

Swagger to zestaw narzędzi do pracy ze specyfikacją OpenAPI. W kontekście NestJS najważniejszy jest Swagger UI - interaktywna strona dokumentacji, która pozwala przeglądać i testować endpointy API bezpośrednio z przeglądarki.

Swagger UI to jak Forum Romanum naszego API - miejsce, gdzie każdy obywatel (developer) może zobaczyć dostępne usługi Imperium, przetestować je i zrozumieć ich działanie.

Dlaczego dokumentacja API jest ważna?

Tak jak Imperium Rzymskie nie mogłoby funkcjonować bez spisanych praw i dekretów, tak nowoczesne API nie powinno istnieć bez dokumentacji:

1. Komunikacja między zespołami - frontend i backend mówią tym samym językiem
2. Onboarding nowych developerów - nowi legioniści szybko poznają strukturę API
3. Testowanie - Swagger UI pozwala testować endpointy bez pisania kodu
4. Generowanie kodu klienta - automatyczne generowanie SDK na podstawie specyfikacji
5. Kontrakty API - jasna umowa między dostawcą i konsumentem API

@nestjs/swagger - Skryba Imperium

W NestJS do tworzenia dokumentacji używamy pakietu

@nestjs/swagger

. Ten pakiet automatycznie generuje specyfikację OpenAPI na podstawie dekoratorów w naszym kodzie:

1import { Controller, Get } from '@nestjs/common';
2import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
3
4@ApiTags('Legiones')
5@Controller('legiones')
6export class LegionController {
7  @ApiOperation({ summary: 'Pobierz wszystkie legiony' })
8  @ApiResponse({ status: 200, description: 'Lista legionów Imperium' })
9  @Get()
10  findAll() {
11    return [
12      { name: 'Legio X Gemina', location: 'Pannonia' },
13      { name: 'Legio III Augusta', location: 'Africa' },
14    ];
15  }
16}

Każdy dekorator

@Api...

to jak pieczęć urzędowa na dokumencie - nadaje oficjalny charakter i opisuje przeznaczenie endpointu.

Podstawowe dekoratory Swagger

| Dekorator | Analogia rzymska | Opis | |-----------|------------------|------| |

@ApiTags()

| Księga annałów | Grupuje endpointy w sekcje | |

@ApiOperation()

| Dekret cesarski | Opisuje pojedynczy endpoint | |

@ApiResponse()

| Edykt odpowiedzi | Definiuje możliwe odpowiedzi | |

@ApiProperty()

| Pieczęć na dokumencie | Opisuje pole w DTO | |

@ApiBearerAuth()

| Signum legionu | Oznacza endpoint jako chroniony |

Ćwiczenie praktyczne

Przyjrzyj się poniższemu kodowi, który pokazuje podstawową konfigurację Swagger w projekcie NestJS: