Πώς δημιουργείτε τεκμηρίωση API με το Swagger;

Question

Accepted Answer

Το NestJS ενσωματώνεται με το **Swagger/OpenAPI** μέσω `@nestjs/swagger` για να **δημιουργεί αυτόματα διαδραστική τεκμηρίωση API** από τον κώδικά σας — ελεγκτές, δρομολογήσεις, DTOs και διακοσμητές. Παράγει ένα περιηγήσιμο UI όπου οι προγραμματιστές μπορούν να εξερευνήσουν και να δοκιμάσουν τα endpoints, που παραμένει συγχρονισμένο με τον κώδικα.

## Ρύθμιση του 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
```

Με λίγες γραμμές, το Swagger σαρώνει την εφαρμογή σας και εξυπηρετεί διαδραστική τεκμηρίωση στο `/api/docs` — αντανακλώντας αυτόματα τις δρομολογήσεις, παραμέτρους και DTOs σας.

## Τεκμηρίωση DTOs και απαντήσεων

```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;
}
```

Οι διακοσμητές `@ApiProperty` προσθέτουν περιγραφές, παραδείγματα και περιορισμούς στα πεδία DTO, εμπλουτίζοντας το δημιουργημένο σχήμα. (Πολλά συμπεραίνονται αυτόματα από τους τύπους TypeScript και τους διακοσμητές `class-validator` — το `CLI plugin` μπορεί να μειώσει ακόμη και αυτό το boilerplate.)

## Τεκμηρίωση endpoints

```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) {}
}
```

Οι διακοσμητές όπως `@ApiTags`, `@ApiOperation` και `@ApiResponse` προσθέτουν περιγραφές, ομαδοποιούν endpoints και τεκμηριώνουν πιθανές απαντήσεις.

## Τι παίρνετε

```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
```

## Γιατί έχει σημασία

Η τεκμηρίωση API είναι απαραίτητη για οποιοδήποτε API που καταναλώνεται από άλλους — ομάδες frontend, εφαρμογές κινητών, τρίτους ενσωματωτές ή ακόμη και τον ίδιο σας στο μέλλον — και η ενσωμάτωση Swagger του NestJS κάνει την παραγωγή τεκμηρίωσης υψηλής ποιότητας εντυπωσιακά εύκολη και αξιόπιστη.

Το κύριο πλεονέκτημα είναι ότι η τεκμηρίωση **δημιουργείται αυτόματα από τον κώδικα** (ελεγκτές, δρομολογήσεις, DTOs και διακοσμητές), οπότε παραμένει **συγχρονισμένη** με την πραγματική υλοποίηση αντί να παρασυρθεί όπως αναπόφευκτα συμβαίνει με τεκμηρίωση γραμμένη με το χέρι.

Η κατανόησή του είναι πολύτιμη επειδή η καλή τεκμηρίωση API βελτιώνει δραματικά την εμπειρία προγραμματιστή και μειώνει την τριβή ενσωμάτωσης: το διαδραστικό **Swagger UI** επιτρέπει στους καταναλωτές να εξερευνήσουν και να *δοκιμάσουν* endpoints απευθείας στο πρόγραμμα περιήγησης, και το δημιουργημένο **OpenAPI spec** μπορεί να οδηγήσει τη δημιουργία client SDK και δοκιμή συμβολαίου.

Η γνώση του τρόπου ρύθμισης του Swagger, του εμπλουτισμού της τεκμηρίωσης με διακοσμητές (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) και της τεκμηρίωσης πιστοποίησης είναι πρακτική, συχνά χρησιμοποιούμενη γνώση — καλά τεκμηριωμένα APIs είναι ένα επαγγελματικό πρότυπο και ένα σημάδι ποιότητας του back-end έργου.

Επειδή το NestJS αξιοποιεί τη δομή του διακοσμητή/DTO για να δημιουργεί τόσα πολλά αυτόματα (με ελάχιστη επιπλέον προσπάθεια), δεν υπάρχει ουσιαστικά δικαιολογία για να μην έχετε εξαιρετική τεκμηρίωση, κάνοντας αυτό μια σημαντική, υψηλής αξίας δυνατότητα στα πραγματικά έργα NestJS.