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

Ćwiczenie praktyczne

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

1// Kroniki Imperium - Wprowadzenie do Swagger
2import { Controller, Get } from '@nestjs/common';
3import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
4
5// Dekoratory Swagger opisuja endpointy jak kroniki cesarskie
6// Kazdy dekorator dodaje informacje do dokumentacji API
7
8@ApiTags('Imperium')
9@Controller()
10export class AppController {
11  @ApiOperation({ summary: 'Status Imperium' })
12  @ApiResponse({ status: 200, description: 'Imperium dziala prawidlowo' })
13  @Get()
14  getStatus() {
15    return {
16      imperium: 'Roma Aeterna',
17      status: 'Aktywne',
18      annales: 'Swagger UI dostepne pod /api/docs',
19    };
20  }
21
22  @ApiOperation({ summary: 'Informacje o API' })
23  @ApiResponse({ status: 200, description: 'Metadane API Imperium' })
24  @Get('info')
25  getInfo() {
26    return {
27      name: 'Imperium Romanum API',
28      version: '1.0',
29      description: 'API do zarzadzania legionami i prowincjami',
30      documentation: '/api/docs',
31    };
32  }
33}
34
35// OpenAPI / Swagger to standard opisu REST API
36// @nestjs/swagger generuje dokumentacje automatycznie
37// Swagger UI pozwala przegladac i testowac endpointy
38
39console.log("Swagger = Kroniki Imperium");
40console.log("OpenAPI = Standard opisu API");
41console.log("@ApiTags = Ksiegi annalow (grupowanie)");
42console.log("@ApiOperation = Dekret cesarski (opis endpointu)");
43console.log("@ApiResponse = Edykt odpowiedzi (mozliwe odpowiedzi)");
44