Jak vygenerujete API dokumentaci pomocí Swagger?

Question

Accepted Answer

NestJS se integruje s **Swagger/OpenAPI** přes `@nestjs/swagger` aby **automaticky generoval interaktivní API dokumentaci** z vašeho kódu — controllerů, routů, DTO a dekorátorů. Vytváří prohlížitelné uživatelské rozhraní, kde vývojáři mohou prozkoumat a testovat endpointy, který je udržován v synchronizaci s kódem.

## Nastavení Swagger

```ts
// main.ts
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

const config = new DocumentBuilder()
  .setTitle("Users API")
  .setDescription("The users API documentation")
  .setVersion("1.0")
  .addBearerAuth()                       // document JWT auth
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api/docs", app, document);   // serve the UI at /api/docs
```

S několika řádky kódu Swagger skenuje vaši aplikaci a podává interaktivní dokumentaci na `/api/docs` — automaticky reflektující vaše routy, parametry a DTO.

## Dokumentace DTO a odpovědí

```ts
export class CreateUserDto {
  @ApiProperty({ example: "ann@example.com", description: "User email" })
  email: string;

@ApiProperty({ minLength: 8 })
  password: string;

@ApiPropertyOptional()                 // optional field in the docs
  age?: number;
}
```

Dekorátory `@ApiProperty` přidávají popisy, příklady a omezení polím DTO, obohacující generované schéma. (Velká část je automaticky odvozena z typů TypeScript a dekorátorů `class-validator` — `CLI plugin` může dále snížit i tuto boilerplate.)

## Dokumentace endpointů

```ts
@ApiTags("users")                        // group endpoints in the UI
@Controller("users")
export class UsersController {
  @Post()
  @ApiOperation({ summary: "Create a user" })
  @ApiResponse({ status: 201, description: "User created", type: User })
  @ApiResponse({ status: 400, description: "Invalid input" })
  create(@Body() dto: CreateUserDto) {}
}
```

Dekorátory jako `@ApiTags`, `@ApiOperation` a `@ApiResponse` přidávají popisy, seskupují endpointy a dokumentují možné odpovědi.

## Co dostanete

```text
✓ Interactive UI (Swagger UI) — browse, read, and TEST endpoints in the browser
✓ Auto-generated, always in sync with the code (no separate doc to maintain)
✓ The OpenAPI spec (JSON) — usable to generate client SDKs, for contract testing, etc.
✓ Request/response schemas, validation rules, auth requirements all documented
```

## Proč je to důležité

API dokumentace je nezbytná pro jakékoli API, které používají ostatní — frontend týmy, mobilní aplikace, třetí strany, nebo i vy sami v budoucnosti — a integrace Swagger v NestJS činí výrobu kvalitní dokumentace pozoruhodně jednoduchou a spolehlivou.

Hlavní výhodou je, že dokumentace je **generována automaticky z kódu** (controllerů, routů, DTO a dekorátorů), takže zůstává **synchronizována** se skutečnou implementací, spíše než aby postupně zastarávala, jak to neměnně dělá ručně psaná dokumentace.

Rozmění se jí vyplatí, protože kvalitní API dokumentace dramaticky zlepšuje zkušenost vývojářů a snižuje tření při integraci: interaktivní **Swagger UI** umožňuje konzumentům prozkoumat a *testovat* endpointy přímo v prohlížeči a generované **OpenAPI specifikace** mohou řídit generování SDK klientů a testování smluv.

Vědět, jak nastavit Swagger, obohatit dokumentaci dekorátory (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) a dokumentovat autentizaci, je praktická, často potřebná znalost — dobře zdokumentovaná API jsou profesionální standard a střípkem kvality back-endové práce.

Protože NestJS využívá svou dekorátor/DTO strukturu k tak automatickému generování (s minimálním dalším úsilím), neexistuje téměř žádný důvod nemít výbornou dokumentaci, což činí tuto schopnost důležitou, vysoce hodnotnou součástí reálných NestJS projektů.