Kurs NestJS · Moduł 11: Swagger i OpenAPI

Projekt główny: Kompletna dokumentacja Imperium API

3 min czytania ·
W tej lekcji3

Nadszedł czas na wielkie dzieło - stworzenie kompletnych Kronik Imperium! W tym projekcie połączysz całą wiedzę z modułu, aby stworzyć w pełni udokumentowane API zarządzania Imperium Rzymskim.

Wymagania projektu

Twoje Kroniki Imperium muszą zawierać:

1. Konfiguracja Swagger w main.ts

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));

  const config = new DocumentBuilder()
    .setTitle('Imperium Romanum API')
    .setDescription('Kompletna dokumentacja API zarządzania Imperium Rzymskim')
    .setVersion('1.0')
    .addTag('Legiones', 'Zarządzanie legionami i żołnierzami')
    .addTag('Provinciae', 'Zarządzanie prowincjami Imperium')
    .addTag('Tributum', 'System podatkowy i skarbiec')
    .addBearerAuth(
      { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
      'JWT-auth',
    )
    .setContact('Konsul Maximus', 'https://imperium.rome', 'consul@rome.gov')
    .setLicense('Lex Romana', 'https://imperium.rome/lex')
    .build();

  const document = SwaggerModule.createDocument(app, config);

  SwaggerModule.setup('api/docs', app, document, {
    customSiteTitle: 'Kroniki Imperium API',
    swaggerOptions: {
      persistAuthorization: true,
      filter: true,
      showRequestDuration: true,
    },
  });

  await app.listen(3000);
}
bootstrap();

2. DTO z pełną dokumentacją

import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';

export enum LegionaryRank {
  MILES = 'Miles',
  OPTIO = 'Optio',
  CENTURIO = 'Centurio',
  TRIBUNUS = 'Tribunus',
  LEGATUS = 'Legatus',
}

export class CreateLegionaryDto {
  @ApiProperty({ description: 'Imię legionisty', example: 'Marcus Aurelius', minLength: 2 })
  name: string;

  @ApiProperty({ description: 'Ranga', enum: LegionaryRank, example: LegionaryRank.MILES })
  rank: LegionaryRank;

  @ApiProperty({ description: 'Przypisany legion', example: 'Legio X Gemina' })
  legio: string;

  @ApiPropertyOptional({ description: 'Lata doświadczenia', example: 3, minimum: 0, maximum: 40 })
  experience?: number;
}

export class LegionaryResponseDto {
  @ApiProperty({ description: 'ID legionisty', example: '64a1b2c3d4e5f6a7b8c9d0e1' })
  id: string;

  @ApiProperty({ description: 'Imię', example: 'Marcus Aurelius' })
  name: string;

  @ApiProperty({ description: 'Ranga', enum: LegionaryRank })
  rank: LegionaryRank;

  @ApiProperty({ description: 'Legion', example: 'Legio X Gemina' })
  legio: string;

  @ApiProperty({ description: 'Doświadczenie', example: 5 })
  experience: number;

  @ApiProperty({ description: 'Data rekrutacji' })
  recruitedAt: Date;
}

3. Kontroler z pełną dokumentacją

import { Controller, Get, Post, Put, Delete, Param, Body, Query, UseGuards } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiParam, ApiQuery, ApiBearerAuth,
  ApiOkResponse, ApiCreatedResponse, ApiNotFoundResponse,
  ApiBadRequestResponse, ApiUnauthorizedResponse } from '@nestjs/swagger';

@ApiTags('Legiones')
@Controller('legiones')
export class LegionController {
  @ApiOperation({ summary: 'Pobierz wszystkie legiony' })
  @ApiOkResponse({ description: 'Lista legionów', type: [LegionaryResponseDto] })
  @ApiQuery({ name: 'rank', required: false, enum: LegionaryRank })
  @Get()
  findAll(@Query('rank') rank?: LegionaryRank) {}

  @ApiOperation({ summary: 'Pobierz legionistę po ID' })
  @ApiParam({ name: 'id', description: 'ID legionisty' })
  @ApiOkResponse({ type: LegionaryResponseDto })
  @ApiNotFoundResponse({ description: 'Legionista nie znaleziony' })
  @Get(':id')
  findOne(@Param('id') id: string) {}

  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ summary: 'Rekrutuj legionistę' })
  @ApiCreatedResponse({ type: LegionaryResponseDto })
  @ApiBadRequestResponse({ description: 'Nieprawidłowe dane' })
  @ApiUnauthorizedResponse({ description: 'Brak autoryzacji' })
  @Post()
  create(@Body() dto: CreateLegionaryDto) {}
}

Podsumowanie modułu

W tym module nauczyłeś się:

  1. Czym jest OpenAPI/Swagger - standard dokumentacji API
  2. Instalacja i konfiguracja - DocumentBuilder i SwaggerModule
  3. Dekoratory kontrolerów - @ApiTags, @ApiOperation, @ApiResponse, @ApiParam, @ApiQuery
  4. Dokumentacja DTO - @ApiProperty z opisami, przykładami i walidacją
  5. Zaawansowane odpowiedzi - dedykowane dekoratory dla każdego kodu statusu
  6. Customization - personalizacja Swagger UI
  7. CLI Plugin - automatyczne generowanie dokumentacji
  8. Wersjonowanie - multiple docs dla różnych wersji API

Teraz Twoje Kroniki Imperium są kompletne! Każdy endpoint jest udokumentowany jak cesarski dekret, a Swagger UI służy jako Forum Annałów dla wszystkich developerów.

Ćwiczenie praktyczne

Stwórz kompletną dokumentację API Imperium Romanum:

Kod do tej lekcji: src/app.controller.ts
// Projekt glowny: Kompletna dokumentacja Imperium API
import { Controller, Get, Post, Put, Delete, Param, Body, Query } from '@nestjs/common';
import {
  ApiTags, ApiOperation, ApiParam, ApiQuery, ApiBearerAuth,
  ApiOkResponse, ApiCreatedResponse, ApiNotFoundResponse,
  ApiBadRequestResponse, ApiUnauthorizedResponse,
} from '@nestjs/swagger';
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';

// ===== DTO =====

enum LegionaryRank {
  MILES = 'Miles',
  OPTIO = 'Optio',
  CENTURIO = 'Centurio',
  TRIBUNUS = 'Tribunus',
  LEGATUS = 'Legatus',
}

class CreateLegionaryDto {
  @ApiProperty({ description: 'Imie legionisty', example: 'Marcus Aurelius' })
  name: string;

  @ApiProperty({ description: 'Ranga', enum: LegionaryRank, example: LegionaryRank.MILES })
  rank: LegionaryRank;

  @ApiProperty({ description: 'Przypisany legion', example: 'Legio X Gemina' })
  legio: string;

  @ApiPropertyOptional({ description: 'Doswiadczenie', example: 3, minimum: 0 })
  experience?: number;
}

class LegionaryResponseDto {
  @ApiProperty({ example: '64a1b2c3d4e5f6a7b8c9d0e1' })
  id: string;

  @ApiProperty({ example: 'Marcus Aurelius' })
  name: string;

  @ApiProperty({ enum: LegionaryRank })
  rank: LegionaryRank;

  @ApiProperty({ example: 'Legio X Gemina' })
  legio: string;

  @ApiProperty({ example: 5 })
  experience: number;
}

// ===== KONTROLER =====

@ApiTags('Legiones')
@Controller('legiones')
class LegionController {
  @ApiOperation({ summary: 'Pobierz wszystkie legiony' })
  @ApiOkResponse({ description: 'Lista legionow', type: [LegionaryResponseDto] })
  @ApiQuery({ name: 'rank', required: false, enum: LegionaryRank })
  @Get()
  findAll(@Query('rank') rank?: LegionaryRank) {
    return [
      { id: '1', name: 'Marcus', rank: 'Centurio', legio: 'Legio X', experience: 10 },
    ];
  }

  @ApiOperation({ summary: 'Pobierz legioniste po ID' })
  @ApiParam({ name: 'id', description: 'ID legionisty' })
  @ApiOkResponse({ type: LegionaryResponseDto })
  @ApiNotFoundResponse({ description: 'Legionista nie znaleziony' })
  @Get(':id')
  findOne(@Param('id') id: string) {
    return { id, name: 'Marcus', rank: 'Centurio', legio: 'Legio X', experience: 10 };
  }

  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ summary: 'Rekrutuj legioniste' })
  @ApiCreatedResponse({ type: LegionaryResponseDto })
  @ApiBadRequestResponse({ description: 'Nieprawidlowe dane' })
  @ApiUnauthorizedResponse({ description: 'Brak autoryzacji' })
  @Post()
  create(@Body() dto: CreateLegionaryDto) {
    return { id: '2', ...dto, experience: dto.experience || 0 };
  }
}

console.log("Kompletna dokumentacja Imperium API");
console.log("DTO: CreateLegionaryDto, LegionaryResponseDto");
console.log("Kontroler: LegionController z pelna dokumentacja");
console.log("Dekoratory: Tags, Operation, Param, Query, Response, Auth");

Hasła z dokumentacji w tej lekcji

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. Które dekoratory Swagger powinien mieć dobrze udokumentowany endpoint GET /:id?

  2. 2. Jak najlepiej zabezpieczyć dostęp do Swagger UI w środowisku produkcyjnym?

To 2 z 4 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Układanie w pionie

    Uporządkuj elementy kompletnej dokumentacji API od konfiguracji do prezentacji:

  • Edytor kodu

    Stwórz CreateArmyDto z enum ArmyUnit, zagnieżdżonym CommanderDto, tablicą provinces i walidacją soldiers

  • Klikanie w kolejności

    Ułóż elementy udokumentowanego pola DTO od dekoratora do typu:

  • Układanie w poziomie

    Ułóż argumenty SwaggerModule.setup() w prawidłowej kolejności:

  • Układanie w pionie

    Uporządkuj strategie wersjonowania od najprostszej do najbardziej zaawansowanej:

  • Klikanie w kolejności

    Ułóż elementy importu dekoratorów Swagger w prawidłowej kolejności:

  • Układanie w pionie

    Uporządkuj etapy tworzenia dokumentacji Swagger od instalacji do korzystania:

  • Układanie w poziomie

    Ułóż elementy dekoratora @ApiResponse w prawidłowej kolejności:

  1. PytaniePełna dokumentacja endpointu GET
  2. Ułóż w kolejnościElementy kompletnej dokumentacji API
  3. Zadanie z kodemZaawansowane DTO z walidacją
  4. Kliknij w kolejnościStruktura udokumentowanego DTO
  5. Ułóż w kolejnościSwaggerModule.setup z opcjami
  6. PytanieZabezpieczenie Swagger w produkcji
  7. Ułóż w kolejnościStrategie wersjonowania API
  8. PytaniePodsumowanie: dekorator @ApiTags
  9. Kliknij w kolejnościKompletny import dekoratorów Swagger
  10. Ułóż w kolejnościProces tworzenia dokumentacji Swagger
  11. Ułóż w kolejnościPełny dekorator @ApiResponse
  12. PytaniePodsumowanie: generowanie dokumentu OpenAPI
  13. Projekt do wysłaniaPrześlij projekt Kroniki Imperium
  14. WideoPodsumowanie modułu

Przydatne artykuły