OpenAPI dan Swagger di NestJS: Dokumen yang Dihasilkan Otomatis dan Selalu Akurat

Dokumentasi API yang sudah usang lebih buruk dari tidak ada dokumentasi — secara aktif menyesatkan pengembang yang menggunakan API Anda. Dalam proyek ERP yang bergerak cepat, mempertahankan file Swagger YAML secara manual tidak mungkin: endpoint berubah, bidang ditambahkan, validasi diperbarui. @nestjs/swagger menyelesaikan ini dengan membaca dekorator TypeScript dan menghasilkan spesifikasi OpenAPI 3.0 yang akurat dari kode aktual Anda.

Cara @nestjs/swagger Menghasilkan Dokumen

@nestjs/swagger menggunakan API refleksi TypeScript untuk membaca informasi tipe dari DTO dan controller Anda. Ini menggabungkan ini dengan dekorator eksplisit (@ApiProperty, @ApiOperation, @ApiResponse) untuk membangun spesifikasi OpenAPI 3.0. Spesifikasi disajikan sebagai JSON di /api-docs/json dan sebagai Swagger UI interaktif di /api-docs.

Plugin CLI NestJS Swagger

Plugin @nestjs/swagger CLI, yang diaktifkan di nest-cli.json, secara otomatis menambahkan dekorator @ApiProperty ke semua properti kelas DTO berdasarkan tipe TypeScript. Tanpa plugin, Anda harus mendekorasi setiap bidang DTO secara manual. Dengan plugin, DTO yang didekorasi class-validator biasa secara otomatis didokumentasikan.

Dekorator Penting

Bahkan dengan plugin CLI, beberapa dekorator menambahkan informasi yang tidak dapat disimpulkan plugin: @ApiOperation mengatur ringkasan dan deskripsi endpoint. @ApiResponse mendokumentasikan kode respons spesifik. @ApiTags mengelompokkan endpoint di sidebar Swagger UI. @ApiSecurity menandai endpoint yang memerlukan otentikasi. Saya menggunakan @ApiOperation pada setiap endpoint dan @ApiResponse untuk setidaknya 200, 400, dan 401 pada rute yang diautentikasi.

@nestjs/swagger Documentation Generation Flow:
────────────────────────────────────────────────────────────
TypeScript Source
  ├── Controllers (@Controller, @Get, @Post, @Version)
  │     └── @ApiOperation, @ApiResponse, @ApiTags
  ├── DTOs (class-validator decorators)
  │     └── CLI Plugin auto-adds @ApiProperty
  └── Types (TypeScript types + JSDoc)
        └── CLI Plugin reads types + comments
                    │
                    ▼ Swagger module reads metadata at startup
              OpenAPI 3.0 JSON spec
                    │
          ┌─────────┴──────────┐
          ▼                    ▼
   /api-docs            /api-docs/json
  (Swagger UI)         (machine-readable)
                              │
                              ▼
                    openapi-generator-cli
                              │
                    TypeScript SDK for frontend

Pengaturan Swagger Produksi Saya

Pengaturan produksi lengkap mencakup: dokumen Swagger yang diversion (satu per versi API), konfigurasi token bearer JWT sehingga fitur 'Try it out' bekerja dengan otentikasi, CSS Swagger UI kustom untuk branding, dan eksposur berbasis lingkungan (Swagger tersedia dalam pengembangan dan staging tetapi tidak dalam produksi).

Menghasilkan SDK Klien dari OpenAPI

Spesifikasi OpenAPI yang dihasilkan NestJS dapat dimasukkan ke generator kode untuk menghasilkan SDK klien yang type-safe. OpenAPI Generator dapat menghasilkan klien TypeScript untuk frontend React/Next.js dari spesifikasi. Ketika Anda mengubah bidang DTO, regenerasi klien untuk menangkap perubahan yang merusak sebelum mencapai produksi.

// main.ts — production Swagger setup
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)
  app.enableVersioning({ type: VersioningType.URI })

  if (process.env.NODE_ENV !== 'production') {
    // V1 documentation
    const v1Config = new DocumentBuilder()
      .setTitle('ERP API v1')
      .setDescription('ERP REST API — v1 (deprecated, migrate to v2)')
      .setVersion('1.0')
      .addBearerAuth({ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' })
      .addServer('/api/v1')
      .build()
    const v1Doc = SwaggerModule.createDocument(app, v1Config, {
      include: [InvoicesV1Module, CustomersV1Module],
    })
    SwaggerModule.setup('api-docs/v1', app, v1Doc)

    // V2 documentation
    const v2Config = new DocumentBuilder()
      .setTitle('ERP API v2')
      .setDescription('ERP REST API — v2 with cursor pagination and improved schemas')
      .setVersion('2.0')
      .addBearerAuth({ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' })
      .addServer('/api/v2')
      .build()
    const v2Doc = SwaggerModule.createDocument(app, v2Config, {
      include: [InvoicesV2Module, CustomersV2Module],
    })
    SwaggerModule.setup('api-docs/v2', app, v2Doc)
  }

  await app.listen(3000)
}

// nest-cli.json — enable Swagger CLI plugin
{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": [{
      "name": "@nestjs/swagger",
      "options": {
        "introspectComments": true,  // JSDoc → descriptions
        "classValidatorShim": true   // class-validator → required/optional
      }
    }]
  }
}

// create-invoice.dto.ts — with JSDoc (plugin reads these)
export class CreateInvoiceDto {
  /** The invoice number (auto-generated if omitted) */
  @IsOptional()
  @IsString()
  invoiceNumber?: string

  /** Total invoice amount in IDR */
  @IsNumber()
  @Min(0)
  amount: number

  /** Customer ID this invoice belongs to */
  @IsUUID()
  customerId: string
}

Mendokumentasikan Otentikasi

Otentikasi JWT didokumentasikan dengan `addBearerAuth()` pada DocumentBuilder dan `@ApiBearerAuth()` pada controller atau rute yang dilindungi. Ini menambahkan tombol 'Authorize' ke Swagger UI di mana penguji dapat menempelkan token JWT mereka. Semua permintaan 'Try it out' berikutnya akan menyertakan header Authorization secara otomatis.

Menjaga Dokumen Sinkron dengan Validasi

Risiko terbesar untuk drift dokumentasi adalah ketika validasi DTO (class-validator) dan dokumentasi OpenAPI berbeda. Bidang mungkin @IsOptional() dalam validasi tetapi tidak ditandai opsional dalam spesifikasi OpenAPI, menyesatkan klien. Perbaikan: gunakan tipe yang dipetakan NestJS (@nestjs/mapped-types) untuk memperluas DTO. Selalu impor tipe yang dipetakan dari @nestjs/swagger, bukan @nestjs/mapped-types, ketika Swagger diaktifkan.

Validasi CI Spesifikasi OpenAPI

Untuk mencegah regresi dokumentasi dari di-deploy, validasi spesifikasi OpenAPI yang dihasilkan di CI. Pada setiap PR, hasilkan spesifikasi dengan skrip dan jalankan melalui validator OpenAPI (`swagger-cli validate api-docs.json`). Lebih baik: jalankan diff antara spesifikasi PR dan spesifikasi cabang utama, dan gagalkan PR jika perubahan yang merusak terdeteksi tanpa bumping versi.

Sumber & Bacaan Lebih Lanjut

• NestJS — OpenAPI Introduction — https://docs.nestjs.com/openapi/introduction
• Speakeasy — How to Generate OpenAPI with NestJS — https://www.speakeasy.com/openapi/frameworks/nestjs
• Dev Centre House — NestJS + Swagger Auto-Generate API Docs — https://www.devcentrehouse.eu/blogs/nestjs-swagger-auto-generate-api-docs/