Kurs NestJS · Moduł 11: Swagger i OpenAPI
Kroniki Imperium: Wprowadzenie do dokumentacji API
W tej lekcji6
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:
// Tak wygląda opis endpointu w formacie OpenAPI
{
"paths": {
"/legiones": {
"get": {
"summary": "Pobierz listę legionów",
"description": "Zwraca wszystkie legiony Imperium",
"responses": {
"200": {
"description": "Lista legionów"
}
}
}
}
}
}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:
- Komunikacja między zespołami - frontend i backend mówią tym samym językiem
- Onboarding nowych developerów - nowi legioniści szybko poznają strukturę API
- Testowanie - Swagger UI pozwala testować endpointy bez pisania kodu
- Generowanie kodu klienta - automatyczne generowanie SDK na podstawie specyfikacji
- 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:
import { Controller, Get } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
@ApiTags('Legiones')
@Controller('legiones')
export class LegionController {
@ApiOperation({ summary: 'Pobierz wszystkie legiony' })
@ApiResponse({ status: 200, description: 'Lista legionów Imperium' })
@Get()
findAll() {
return [
{ name: 'Legio X Gemina', location: 'Pannonia' },
{ name: 'Legio III Augusta', location: 'Africa' },
];
}
}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:
Kod do tej lekcji: src/app.controller.ts
// Kroniki Imperium - Wprowadzenie do Swagger
import { Controller, Get } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
// Dekoratory Swagger opisuja endpointy jak kroniki cesarskie
// Kazdy dekorator dodaje informacje do dokumentacji API
@ApiTags('Imperium')
@Controller()
export class AppController {
@ApiOperation({ summary: 'Status Imperium' })
@ApiResponse({ status: 200, description: 'Imperium dziala prawidlowo' })
@Get()
getStatus() {
return {
imperium: 'Roma Aeterna',
status: 'Aktywne',
annales: 'Swagger UI dostepne pod /api/docs',
};
}
@ApiOperation({ summary: 'Informacje o API' })
@ApiResponse({ status: 200, description: 'Metadane API Imperium' })
@Get('info')
getInfo() {
return {
name: 'Imperium Romanum API',
version: '1.0',
description: 'API do zarzadzania legionami i prowincjami',
documentation: '/api/docs',
};
}
}
// OpenAPI / Swagger to standard opisu REST API
// @nestjs/swagger generuje dokumentacje automatycznie
// Swagger UI pozwala przegladac i testowac endpointy
console.log("Swagger = Kroniki Imperium");
console.log("OpenAPI = Standard opisu API");
console.log("@ApiTags = Ksiegi annalow (grupowanie)");
console.log("@ApiOperation = Dekret cesarski (opis endpointu)");
console.log("@ApiResponse = Edykt odpowiedzi (mozliwe odpowiedzi)");
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Czym jest OpenAPI (dawniej Swagger Specification)?
2. Jaka jest główna funkcja Swagger UI w kontekście NestJS?
To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Uzupełnij konfigurację DocumentBuilder ustawiając title, description i version
- Klikanie w kolejności
Ułóż elementy importu dekoratora ApiTags w prawidłowej kolejności:
- Układanie w pionie
Uporządkuj korzyści z dokumentacji API od najbardziej bezpośredniej do długoterminowej: