Swagger ile API dokumentasyonunu nasıl oluşturursunuz?

Question

Accepted Answer

NestJS, `@nestjs/swagger` aracılığıyla **Swagger/OpenAPI** ile entegre olarak kodunuzdan — controller'lar, rotalar, DTO'lar ve dekoratörler — **otomatik olarak etkileşimli API dokumentasyonu oluşturur**. Geliştiricilerin endpoint'leri keşfedip test edebileceği bir tarayıcı arayüzü üretir ve kod ile senkronize tutulur.

## Swagger'ı ayarlama

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

Birkaç satırla Swagger uygulamanızı tarar ve etkileşimli dokları `/api/docs` adresinde sunar — rotalarınızı, parametrelerinizi ve DTO'larınızı otomatik olarak yansıtır.

## DTO'ları ve yanıtları dokümante etme

```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` dekoratörleri DTO alanlarına açıklamalar, örnekler ve kısıtlamalar ekleyerek oluşturulan şemayı zenginleştirir. (Çoğu otomatik olarak TypeScript türlerinden ve `class-validator` dekoratörlerinden çıkarılır — `CLI plugin'i` bu standart kodu daha da azaltabilir.)

## Endpoint'leri dokümante etme

```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` ve `@ApiResponse` gibi dekoratörler açıklamalar ekler, endpoint'leri gruplandırır ve olası yanıtları dokümante eder.

## Ne elde edersiniz

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

## Neden önemli

API dokumentasyonu, herhangi bir API'yi tüketen — frontend takımları, mobil uygulamalar, üçüncü taraf entegrasyonları veya hatta gelecekteki siziniz — için gereklidir ve NestJS'nin Swagger entegrasyonu yüksek kaliteli doklar üretmeyi dikkat çekici derecede kolay ve güvenilir hale getirir.

Temel avantaj, dokumentasyonun **koddan otomatik olarak oluşturulması** (controller'lar, rotalar, DTO'lar ve dekoratörler), böylece **senkronize kalması** gerçek implementasyonla, el yazısı doklar gibi kaçınılmaz olarak eski kalmak yerine.

Bunu anlamak değerlidir çünkü iyi API dokları geliştirici deneyimini dramatik olarak iyileştirir ve entegrasyon sürtünmesini azaltır: etkileşimli **Swagger UI**, tüketicilerin endpoint'leri doğrudan tarayıcıda keşfedip *test etmesine* izin verir ve oluşturulan **OpenAPI spec'i** istemci SDK oluşturma ve kontrat testini yönlendirebilir.

Swagger'ı ayarlamayı, dekoratörlerle dokları zenginleştirmeyi (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) ve kimlik doğrulamayı dokümante etmeyi bilmek pratiktir, sık ihtiyaç duyulan bilgidir — iyi dokümante edilmiş API'ler bir profesyonel standarttır ve kaliteli arka uç çalışmasının bir göstergesidir.

NestJS, dekoratör/DTO yapısından çok şeyi otomatik olarak oluşturmak için kaldıraç yaptığından (minimal ek çabayla), mükemmel doklar bulundurmamak için bahane yoktur, bu da bunu gerçek NestJS projelerinde önemli, yüksek değerli bir yeteneği yapar.