Zaawansowane odpowiedzi - edykty cesarskie

W kancelarii cesarskiej każdy edykt musiał jasno określać konsekwencje - co się stanie w przypadku powodzenia, co w przypadku naruszenia prawa, a co gdy petent nie ma uprawnień. W Swagger dokumentujemy to za pomocą specjalizowanych dekoratorów odpowiedzi.

Specjalizowane dekoratory odpowiedzi

Zamiast ogólnego

@ApiResponse()

, NestJS Swagger oferuje dedykowane dekoratory dla każdego kodu statusu HTTP:

1import {
2  ApiOkResponse,
3  ApiCreatedResponse,
4  ApiNotFoundResponse,
5  ApiBadRequestResponse,
6  ApiUnauthorizedResponse,
7  ApiForbiddenResponse,
8  ApiConflictResponse,
9  ApiInternalServerErrorResponse,
10} from '@nestjs/swagger';

@ApiOkResponse (200) - Dekret wykonany

Używamy go gdy endpoint zwraca dane pomyślnie:

1@ApiOkResponse({
2  description: 'Lista legionów Imperium',
3  type: [LegionResponseDto],
4})
5@Get()
6findAll(): LegionResponseDto[] {
7  return this.legionService.findAll();
8}

@ApiCreatedResponse (201) - Nowy rekrut przyjęty

Dla endpointów tworzących nowe zasoby:

1@ApiCreatedResponse({
2  description: 'Legionista został pomyślnie zrekrutowany',
3  type: LegionaryResponseDto,
4})
5@Post()
6recruit(@Body() dto: CreateLegionaryDto): LegionaryResponseDto {
7  return this.legionService.recruit(dto);
8}

@ApiNotFoundResponse (404) - Nie znaleziono w annałach

Gdy żądany zasób nie istnieje:

1@ApiNotFoundResponse({
2  description: 'Legion o podanym ID nie został znaleziony w annałach Imperium',
3})
4@Get(':id')
5findOne(@Param('id') id: string) {
6  return this.legionService.findOne(id);
7}

@ApiBadRequestResponse (400) - Wadliwy pergamin

Gdy dane wejściowe są nieprawidłowe:

1@ApiBadRequestResponse({
2  description: 'Nieprawidłowe dane rekrutacyjne - sprawdź wymagane pola',
3})
4@Post()
5recruit(@Body() dto: CreateLegionaryDto) {
6  return this.legionService.recruit(dto);
7}

@ApiUnauthorizedResponse (401) - Brak pieczęci cesarskiej

Gdy użytkownik nie jest uwierzytelniony:

1@ApiUnauthorizedResponse({
2  description: 'Brak ważnego tokenu JWT - wymagana pieczęć cesarska',
3})
4@ApiBearerAuth('JWT-auth')
5@UseGuards(JwtAuthGuard)
6@Delete(':id')
7dismiss(@Param('id') id: string) {
8  return this.legionService.dismiss(id);
9}

Łączenie wielu dekoratorów odpowiedzi

W praktyce każdy endpoint powinien dokumentować wszystkie możliwe odpowiedzi:

1@ApiOperation({ summary: 'Awansuj legionistę' })
2@ApiOkResponse({
3  description: 'Legionista został awansowany',
4  type: LegionaryResponseDto,
5})
6@ApiNotFoundResponse({
7  description: 'Legionista nie znaleziony',
8})
9@ApiUnauthorizedResponse({
10  description: 'Brak autoryzacji - wymagany token JWT',
11})
12@ApiBadRequestResponse({
13  description: 'Nieprawidłowa ranga docelowa',
14})
15@ApiBearerAuth('JWT-auth')
16@UseGuards(JwtAuthGuard)
17@Patch(':id/promote')
18promote(
19  @Param('id') id: string,
20  @Body() dto: PromoteLegionaryDto,
21): LegionaryResponseDto {
22  return this.legionService.promote(id, dto);
23}

Typ odpowiedzi z DTO

Opcja

type

w dekoratorach odpowiedzi pozwala powiązać odpowiedź z konkretnym DTO:

1// Odpowiedź pojedynczego obiektu
2@ApiOkResponse({ type: LegionResponseDto })
3
4// Odpowiedź tablicy obiektów
5@ApiOkResponse({ type: [LegionResponseDto] })
6
7// Odpowiedź z opisem
8@ApiOkResponse({
9  description: 'Szczegóły legionu',
10  type: LegionResponseDto,
11})

Dzięki temu Swagger UI wyświetli pełny schemat odpowiedzi z przykładowymi wartościami.

Ćwiczenie praktyczne

Dodaj zaawansowane dekoratory odpowiedzi do kontrolera trybutów Imperium: