Kurs NestJS · Moduł 11: Swagger i OpenAPI
Projekt główny: Kompletna dokumentacja Imperium API
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ę:
- Czym jest OpenAPI/Swagger - standard dokumentacji API
- Instalacja i konfiguracja - DocumentBuilder i SwaggerModule
- Dekoratory kontrolerów - @ApiTags, @ApiOperation, @ApiResponse, @ApiParam, @ApiQuery
- Dokumentacja DTO - @ApiProperty z opisami, przykładami i walidacją
- Zaawansowane odpowiedzi - dedykowane dekoratory dla każdego kodu statusu
- Customization - personalizacja Swagger UI
- CLI Plugin - automatyczne generowanie dokumentacji
- 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. Które dekoratory Swagger powinien mieć dobrze udokumentowany endpoint GET /:id?
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:
Zadania po tej lekcji
- PytaniePełna dokumentacja endpointu GET
- Ułóż w kolejnościElementy kompletnej dokumentacji API
- Zadanie z kodemZaawansowane DTO z walidacją
- Kliknij w kolejnościStruktura udokumentowanego DTO
- Ułóż w kolejnościSwaggerModule.setup z opcjami
- PytanieZabezpieczenie Swagger w produkcji
- Ułóż w kolejnościStrategie wersjonowania API
- PytaniePodsumowanie: dekorator @ApiTags
- Kliknij w kolejnościKompletny import dekoratorów Swagger
- Ułóż w kolejnościProces tworzenia dokumentacji Swagger
- Ułóż w kolejnościPełny dekorator @ApiResponse
- PytaniePodsumowanie: generowanie dokumentu OpenAPI
- Projekt do wysłaniaPrześlij projekt Kroniki Imperium
- WideoPodsumowanie modułu