Projekt główny: Kompletna dokumentacja Imperium API

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

1import { NestFactory } from '@nestjs/core';
2import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
3import { ValidationPipe } from '@nestjs/common';
4import { AppModule } from './app.module';
5
6async function bootstrap() {
7  const app = await NestFactory.create(AppModule);
8
9  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
10
11  const config = new DocumentBuilder()
12    .setTitle('Imperium Romanum API')
13    .setDescription('Kompletna dokumentacja API zarządzania Imperium Rzymskim')
14    .setVersion('1.0')
15    .addTag('Legiones', 'Zarządzanie legionami i żołnierzami')
16    .addTag('Provinciae', 'Zarządzanie prowincjami Imperium')
17    .addTag('Tributum', 'System podatkowy i skarbiec')
18    .addBearerAuth(
19      { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
20      'JWT-auth',
21    )
22    .setContact('Konsul Maximus', 'https://imperium.rome', 'consul@rome.gov')
23    .setLicense('Lex Romana', 'https://imperium.rome/lex')
24    .build();
25
26  const document = SwaggerModule.createDocument(app, config);
27
28  SwaggerModule.setup('api/docs', app, document, {
29    customSiteTitle: 'Kroniki Imperium API',
30    swaggerOptions: {
31      persistAuthorization: true,
32      filter: true,
33      showRequestDuration: true,
34    },
35  });
36
37  await app.listen(3000);
38}
39bootstrap();

2. DTO z pełną dokumentacją

1import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
2
3export enum LegionaryRank {
4  MILES = 'Miles',
5  OPTIO = 'Optio',
6  CENTURIO = 'Centurio',
7  TRIBUNUS = 'Tribunus',
8  LEGATUS = 'Legatus',
9}
10
11export class CreateLegionaryDto {
12  @ApiProperty({ description: 'Imię legionisty', example: 'Marcus Aurelius', minLength: 2 })
13  name: string;
14
15  @ApiProperty({ description: 'Ranga', enum: LegionaryRank, example: LegionaryRank.MILES })
16  rank: LegionaryRank;
17
18  @ApiProperty({ description: 'Przypisany legion', example: 'Legio X Gemina' })
19  legio: string;
20
21  @ApiPropertyOptional({ description: 'Lata doświadczenia', example: 3, minimum: 0, maximum: 40 })
22  experience?: number;
23}
24
25export class LegionaryResponseDto {
26  @ApiProperty({ description: 'ID legionisty', example: '64a1b2c3d4e5f6a7b8c9d0e1' })
27  id: string;
28
29  @ApiProperty({ description: 'Imię', example: 'Marcus Aurelius' })
30  name: string;
31
32  @ApiProperty({ description: 'Ranga', enum: LegionaryRank })
33  rank: LegionaryRank;
34
35  @ApiProperty({ description: 'Legion', example: 'Legio X Gemina' })
36  legio: string;
37
38  @ApiProperty({ description: 'Doświadczenie', example: 5 })
39  experience: number;
40
41  @ApiProperty({ description: 'Data rekrutacji' })
42  recruitedAt: Date;
43}

3. Kontroler z pełną dokumentacją

1import { Controller, Get, Post, Put, Delete, Param, Body, Query, UseGuards } from '@nestjs/common';
2import { ApiTags, ApiOperation, ApiParam, ApiQuery, ApiBearerAuth,
3  ApiOkResponse, ApiCreatedResponse, ApiNotFoundResponse,
4  ApiBadRequestResponse, ApiUnauthorizedResponse } from '@nestjs/swagger';
5
6@ApiTags('Legiones')
7@Controller('legiones')
8export class LegionController {
9  @ApiOperation({ summary: 'Pobierz wszystkie legiony' })
10  @ApiOkResponse({ description: 'Lista legionów', type: [LegionaryResponseDto] })
11  @ApiQuery({ name: 'rank', required: false, enum: LegionaryRank })
12  @Get()
13  findAll(@Query('rank') rank?: LegionaryRank) {}
14
15  @ApiOperation({ summary: 'Pobierz legionistę po ID' })
16  @ApiParam({ name: 'id', description: 'ID legionisty' })
17  @ApiOkResponse({ type: LegionaryResponseDto })
18  @ApiNotFoundResponse({ description: 'Legionista nie znaleziony' })
19  @Get(':id')
20  findOne(@Param('id') id: string) {}
21
22  @ApiBearerAuth('JWT-auth')
23  @ApiOperation({ summary: 'Rekrutuj legionistę' })
24  @ApiCreatedResponse({ type: LegionaryResponseDto })
25  @ApiBadRequestResponse({ description: 'Nieprawidłowe dane' })
26  @ApiUnauthorizedResponse({ description: 'Brak autoryzacji' })
27  @Post()
28  create(@Body() dto: CreateLegionaryDto) {}
29}

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: