Kurs NestJS · Moduł 11: Swagger i OpenAPI
Dekoratory kontrolerów - pieczęcie na dekretach
W tej lekcji5
Dekret bez pieczęci to kartka. Nie wiadomo, kto go wydał, czego dotyczy ani czy w ogóle obowiązuje - a urzędnik w prowincji musi to rozstrzygnąć, zanim cokolwiek zrobi.
Endpoint bez opisu jest dokładnie taki sam. Swagger sam odczyta z kodu ścieżkę i metodę HTTP, ale nie odgadnie, co ten endpoint robi, które parametry są obowiązkowe ani co oznacza zwrócony przez niego kod. Dekoratory z pakietu @nestjs/swagger dopisują to, czego z samego kodu nie widać.
Ważna uwaga na początek: wszystkie te dekoratory tylko opisują. Żaden nie zmienia zachowania aplikacji - endpoint bez @ApiOperation działa tak samo, po prostu w dokumentacji jest bezimienny.
@ApiTags i @ApiOperation
Pierwsze dwie pieczęcie odpowiadają na pytania „gdzie to szukać" i „co to robi":
@ApiTags('Prowincje')
@Controller('provinces')
export class ProvincesController {
@ApiOperation({
summary: 'Lista prowincji',
description: 'Zwraca wszystkie prowincje Imperium wraz z ich namiestnikami.',
})
@Get()
findAll() {
return this.provincesService.findAll();
}
}@ApiTags() grupuje endpointy w sekcje - w Swagger UI powstaje z tego rozwijana grupa. Stawiasz go nad klasą kontrolera, bo grupowanie dotyczy wszystkich jego metod naraz. Można podać kilka tagów po przecinku, gdy kontroler należy do dwóch obszarów.
@ApiOperation() przyjmuje dwie główne właściwości: summary i description. Nie url i method - te NestJS odczytuje z @Get i @Controller. Nie host i port - to konfiguracja serwera, nie opis endpointu. I nie controller ani service - to nazwy klas, o których dokumentacja nie musi wiedzieć.
Różnica między nimi jest praktyczna: summary to jedno zdanie widoczne na liście endpointów, description - dłuższy tekst rozwijany po kliknięciu. Jeśli masz napisać tylko jedno, pisz summary.
@ApiParam kontra @ApiQuery
Te dwa dekoratory mylą się najczęściej, bo oba opisują „coś, co przychodzi w adresie". Rozstrzyga miejsce w URL-u:
@ApiParam({ name: 'id', description: 'Identyfikator prowincji' })
@Get(':id')
findOne(@Param('id') id: string) {
return this.provincesService.findOne(id);
}@ApiParam() opisuje parametry w ścieżce URL (route parameters) - te, które w trasie zapisujesz z dwukropkiem, jak :id, i które są częścią adresu. W /provinces/7 siódemka jest parametrem ścieżki.
@ApiQuery() opisuje parametry zapytania - te po znaku ? w URL. W /provinces?region=Gallia&page=2 parametrami zapytania są region i page. Nie wykonuje żadnego zapytania do bazy danych, nie definiuje schematu GraphQL i nie tworzy query buildera dla ORM-a - słowo „query" odnosi się tu wyłącznie do części adresu.
Pozostałe miejsca mają własne dekoratory: nagłówki HTTP opisuje @ApiHeader, a ciało żądania (request body) - @ApiBody. Cztery różne miejsca, cztery różne dekoratory; pomyłka nie da błędu, tylko dokumentację opisującą coś, czego tam nie ma.
Budowa @ApiQuery
Parametry zapytania bywają opcjonalne i właśnie to trzeba w dokumentacji zaznaczyć:
@ApiQuery({
name: 'province',
required: false,
})
@Get('search')
search(@Query('province') province?: string) {
return this.provincesService.search(province);
}Kolejność zapisu jest stała: @ApiQuery({ otwiera dekorator, name: 'province', podaje nazwę parametru - to jedyne pole obowiązkowe - required: false oznacza go jako opcjonalny, a }) domyka.
required domyślnie ma wartość true, więc opcjonalność trzeba zaznaczyć jawnie. Pominięcie tego jest drobiazgiem, który kosztuje cudzy czas: w Swagger UI parametr pokaże się jako wymagany, a ktoś zbuduje klienta wysyłającego region przy każdym wywołaniu.
Kolejność na endpointcie
Gdy zbierzemy wszystko razem, dekoratory układają się od najogólniejszego do najbardziej szczegółowego:
@ApiTags('Prowincje')
@Controller('provinces')
export class ProvincesController {
@ApiOperation({ summary: 'Szczegóły prowincji' })
@ApiResponse({ status: 200, description: 'Prowincja odnaleziona' })
@ApiResponse({ status: 404, description: 'Nie ma takiej prowincji' })
@ApiParam({ name: 'id', description: 'Identyfikator prowincji' })
@ApiBearerAuth('JWT-auth')
@Get(':id')
findOne(@Param('id') id: string) {
return this.provincesService.findOne(id);
}
}Czyta się to z góry na dół: @ApiTags('Nazwa') na klasie kontrolera obejmuje wszystkie metody, potem nad konkretną metodą @ApiOperation({ summary }) mówi, co ona robi, następnie @ApiResponse({ status }) wylicza możliwe odpowiedzi, a na końcu wykonuje się ciało metody.
@ApiResponse() przyjmuje kod statusu i opis; można go podać wiele razy, po jednym na każdą możliwą odpowiedź. W następnych lekcjach zastąpimy go krótszymi odpowiednikami w rodzaju @ApiOkResponse.
@ApiBearerAuth('JWT-auth') oznacza endpoint jako chroniony - w Swagger UI pojawi się przy nim pole na token, a podana nazwa musi zgadzać się z konfiguracją addBearerAuth.
Podsumowanie
Dekret bez pieczęci to kartka:
- dekoratory Swagger tylko opisują - nie zmieniają zachowania endpointu,
@ApiTags()grupuje endpointy i stoi nad klasą kontrolera,@ApiOperation()przyjmujesummaryidescription- nieurl/method, niehost/port, niecontroller/service,@ApiParam()opisuje parametry w ścieżce URL (te z dwukropkiem, jak:id),@ApiQuery()opisuje parametry zapytania po znaku?- nie odpytuje bazy, nie definiuje GraphQL-a, nie buduje zapytań ORM,- nagłówki opisuje
@ApiHeader, ciało żądania -@ApiBody, - budowa
@ApiQuery:@ApiQuery({→name: 'province',→required: false→}); bezrequired: falseparametr uchodzi za wymagany, - kolejność:
@ApiTags('Nazwa')na klasie →@ApiOperation({ summary })nad metodą →@ApiResponse({ status })nad metodą → ciało metody, @ApiBearerAuth('JWT-auth')oznacza endpoint chroniony tokenem.
W następnej lekcji zejdziemy poziom niżej - do dokumentowania samych DTO, czyli tego, co w tych żądaniach i odpowiedziach naprawdę siedzi. A na razie zapamiętaj: dokumentacja opisuje to, co napisałeś w dekoratorze, nie to, co robi kod. Rozjazd między nimi jest gorszy niż brak dokumentacji, bo w ten pierwszy ktoś uwierzy.
Kod do tej lekcji: src/province.controller.ts
// Dekoratory Swagger na kontrolerze prowincji
import { Controller, Get, Post, Param, Body, Query } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse, ApiParam, ApiQuery } from '@nestjs/swagger';
// TODO: Dodaj dekorator @ApiTags('Provinciae')
@Controller('provinciae')
export class ProvinceController {
// TODO: Dodaj @ApiOperation z summary i description
// TODO: Dodaj @ApiResponse dla statusu 200
@Get()
findAll() {
return [
{ name: 'Pannonia', governor: 'Lucius Verus' },
{ name: 'Britannia', governor: 'Agricola' },
{ name: 'Africa', governor: 'Septimius' },
];
}
// TODO: Dodaj @ApiOperation z summary
// TODO: Dodaj @ApiParam opisujacy parametr 'id'
// TODO: Dodaj @ApiResponse dla 200 i 404
@Get(':id')
findOne(@Param('id') id: string) {
return { name: 'Pannonia', governor: 'Lucius Verus', legions: 3 };
}
// TODO: Dodaj @ApiOperation z summary
// TODO: Dodaj @ApiQuery dla 'region' (opcjonalne)
// TODO: Dodaj @ApiQuery dla 'minLegions' (opcjonalne, typ Number)
@Get('search')
search(
@Query('region') region?: string,
@Query('minLegions') minLegions?: number,
) {
return [{ name: 'Pannonia', region: 'Europa', legions: 3 }];
}
// TODO: Dodaj @ApiOperation z summary
// TODO: Dodaj @ApiResponse dla 201
@Post()
create(@Body() dto: any) {
return { id: '1', ...dto };
}
}
console.log("Dekoratory kontrolerow Swagger:");
console.log("@ApiTags('nazwa') - grupuje endpointy");
console.log("@ApiOperation({ summary, description })");
console.log("@ApiResponse({ status, description })");
console.log("@ApiParam({ name, description, example })");
console.log("@ApiQuery({ name, required, description })");
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Jakie główne właściwości przyjmuje dekorator @ApiOperation()?
2. Kiedy używamy dekoratora @ApiParam() w kontrolerze NestJS?
To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Dodaj @ApiQuery do endpointu wyszukiwania i @ApiParam do endpointu z parametrem :id
- Układanie w pionie
Uporządkuj dekoratory Swagger na endpointcie od dekoratora klasy do ciała metody:
- Klikanie w kolejności
Ułóż elementy dekoratora @ApiQuery w prawidłowej kolejności:
- Edytor kodu
Dodaj @ApiTags, @ApiOperation, @ApiResponse, @ApiParam i @ApiQuery do kontrolera prowincji