# OpenAPI dan Swagger di NestJS: Dokumen yang Dihasilkan Otomatis dan Selalu Akurat > Cara menyiapkan @nestjs/swagger agar dokumentasi API Anda dihasilkan dari kode dan tidak pernah basi — dengan pola dekorator yang saya gunakan. URL: https://www.matthewswong.com/id/blog/openapi-swagger-nestjs/ - Author: Matthews Wong (https://www.matthewswong.com/id/about/) - Published: 2025-06-10 - Updated: 2025-06-10 - Category: Web Dev 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. > Dari pengalaman saya menghasilkan dokumen API NestJS: aktifkan opsi `introspectComments` dalam konfigurasi plugin Swagger untuk secara otomatis menghasilkan deskripsi bidang dari komentar JSDoc pada properti DTO Anda. Alih-alih `@ApiProperty('{ description: ''Tanggal faktur'' }')`, cukup tulis komentar JSDoc: `/** Tanggal faktur dalam format ISO 8601 */` di atas properti. Plugin mengekstrak ini dan menambahkannya ke spesifikasi OpenAPI. ## 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. > **Swagger UI di Produksi Mengekspos Kontrak API Anda** > Swagger UI di /api-docs adalah peta lengkap dari area permukaan API Anda — semua endpoint, semua parameter, semua skema respons. Membiarkannya dapat diakses secara publik di produksi memberi penyerang panduan terperinci ke API Anda. Minimal, letakkan di balik otentikasi dasar atau IP allowlisting. Lebih baik: ekspos hanya di lingkungan non-produksi. ## 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 - Speakeasy — How to Generate OpenAPI with NestJS - Dev Centre House — NestJS + Swagger Auto-Generate API Docs ## Source links - https://docs.nestjs.com/openapi/introduction - https://www.speakeasy.com/openapi/frameworks/nestjs - https://www.devcentrehouse.eu/blogs/nestjs-swagger-auto-generate-api-docs/ ## FAQ ### Mengapa @nestjs/swagger lebih baik daripada mempertahankan file Swagger YAML secara manual? File Swagger YAML yang dikelola secara manual mudah menjadi usang saat endpoint berubah, bidang ditambahkan, atau validasi diperbarui — terutama dalam proyek ERP yang bergerak cepat. @nestjs/swagger membaca dekorator TypeScript dan menghasilkan spesifikasi OpenAPI 3.0 yang akurat langsung dari kode Anda, sehingga setiap perubahan DTO atau rute baru langsung tercermin dalam dokumentasi tanpa langkah manual tambahan. ### Apa yang dilakukan plugin CLI NestJS Swagger, dan bagaimana cara mengaktifkannya? Plugin CLI secara otomatis menambahkan dekorator @ApiProperty ke semua properti kelas DTO berdasarkan tipe TypeScript-nya, sehingga Anda tidak perlu menganotasi setiap bidang secara manual. Plugin ini juga membaca komentar JSDoc dan menggunakannya sebagai deskripsi bidang ketika opsi introspectComments diaktifkan. Anda mengaktifkannya dengan menambahkannya ke array plugins di nest-cli.json lalu me-restart dev server. ### Mengapa mapped types seperti PartialType harus diimpor dari @nestjs/swagger, bukan dari @nestjs/mapped-types? Ketika Swagger diaktifkan, versi PartialType dari @nestjs/swagger tidak hanya membuat semua bidang opsional di TypeScript (sesuai perilaku class-validator), tetapi juga menandai bidang-bidang tersebut sebagai tidak wajib dalam spesifikasi OpenAPI yang dihasilkan. Mengimpor dari @nestjs/mapped-types justru menghilangkan anotasi OpenAPI tersebut, sehingga spesifikasi salah menggambarkan bidang mana yang opsional dan menyesatkan konsumen API. ### Apakah Swagger UI boleh diakses secara publik di lingkungan produksi? Tidak — Swagger UI di /api-docs adalah peta lengkap dari seluruh endpoint, parameter, dan skema respons API Anda, yang dapat dijadikan panduan terperinci oleh penyerang. Minimal, letakkan di balik autentikasi dasar atau IP allowlisting; pendekatan yang direkomendasikan adalah hanya mengeksposnya di lingkungan non-produksi dengan memeriksa process.env.NODE_ENV dan mengembalikan 404 atau halaman login untuk path /api-docs di produksi. ### Bagaimana spesifikasi OpenAPI yang dihasilkan dapat digunakan untuk menjaga sinkronisasi antara frontend dan backend? Spesifikasi yang disajikan di /api-docs/json dapat dimasukkan ke OpenAPI Generator untuk menghasilkan klien TypeScript yang type-safe untuk frontend React atau Next.js, menggunakan generator typescript-axios. Klien yang dihasilkan memiliki antarmuka request dan response yang bertipe dan persis sesuai dengan DTO backend. Ketika bidang DTO berubah, regenerasi klien akan mengungkap perubahan yang merusak sebelum mencapai produksi. --- - HTML version: https://www.matthewswong.com/id/blog/openapi-swagger-nestjs/ - English: https://www.matthewswong.com/en/blog/openapi-swagger-nestjs/ - Site index for agents: https://www.matthewswong.com/llms.txt - Sitemap: https://www.matthewswong.com/sitemap.xml - API description (OpenAPI): https://www.matthewswong.com/openapi.json