Kurs NestJS · Moduł 11: Swagger i OpenAPI

Kroniki Imperium: Wprowadzenie do dokumentacji API

3 min czytania ·
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:

  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:

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

DekoratorAnalogia rzymskaOpis
@ApiTags()Księga annałówGrupuje endpointy w sekcje
@ApiOperation()Dekret cesarskiOpisuje pojedynczy endpoint
@ApiResponse()Edykt odpowiedziDefiniuje możliwe odpowiedzi
@ApiProperty()Pieczęć na dokumencieOpisuje pole w DTO
@ApiBearerAuth()Signum legionuOznacza 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. 1. Czym jest OpenAPI (dawniej Swagger Specification)?

  2. 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:

  1. PytanieCzym jest OpenAPI
  2. PytanieSwagger UI w NestJS
  3. Zadanie z kodemPodstawowa konfiguracja Swagger
  4. PytaniePakiet @nestjs/swagger
  5. Kliknij w kolejnościImport dekoratora ApiTags
  6. Ułóż w kolejnościKorzyści z dokumentacji API

Przydatne artykuły