Designing a Self-Documented API with NestJS & Swagger
Banyak API gagal bukan karena lambat atau bug, tapi karena tidak jelas. Di artikel ini, kita akan membahas bagaimana membangun REST API menggunakan NestJS dan Swagger dengan pendekatan documentation-first — di mana dokumentasi bukan tambahan, tapi bagian dari desain sistem sejak awal. Artikel ini adalah bagian pertama dari seri NestJS Starter Kits, dimulai dari fondasi yang sering diremehkan: API documentation.
Sebagai backend developer, mungkin kamu pernah ada di situasi ini:
- API sudah jalan
- Endpoint sudah banyak
- Frontend mulai integrasi
- Lalu muncul pertanyaan:
“Mas, ini response-nya bentuknya gimana ya?”
“Kalau error, status code-nya apa?”
“Field ini optional atau wajib?”
Dan kamu menjawab sambil buka kode.
Kalau ini sering terjadi, masalahnya bukan di frontend — tapi di cara kita mendesain API.
API yang baik seharusnya:
- Bisa dipahami tanpa baca source code
- Punya kontrak yang jelas
- Bisa di-explore tanpa tanya developer backend
Di sinilah Swagger seharusnya berperan.
Sayangnya, sering kali Swagger baru ditambahkan belakangan — sekadar formalitas.
Swagger Itu Bukan Sekadar UI
Banyak project menggunakan Swagger hanya sebagai:
- Auto-generated API list
- Testing endpoint via browser
Padahal Swagger bisa jauh lebih dari itu.
Kesalahan yang sering saya temui:
- DTO tidak diberi metadata Swagger
- Response tidak konsisten
- Error response tidak terdokumentasi
- Swagger tidak mencerminkan behavior asli API
Akibatnya?
Swagger ada, tapi tetap tidak bisa diandalkan.
Di titik ini, Swagger gagal menjalankan fungsinya sebagai alat komunikasi lintas tim.
Studi Kasus: Internal User Management API
Untuk starter kit ini, saya menggunakan studi kasus yang sangat umum:
Internal User Management API
Digunakan oleh:
- Frontend dashboard
- Mobile app (opsional)
- QA untuk testing
- Product untuk validasi flow
Fitur dasarnya sederhana:
- List users
- Get user detail
- Create, update, delete user
Justru karena sederhana, kasus ini ideal untuk menunjukkan:
- Pentingnya dokumentasi
- Konsistensi response
- Kejelasan kontrak API
Filosofi Starter Kit nestjs-swagger
Starter kit ini dibangun dengan satu prinsip utama:
If it’s not documented, it doesn’t exist.
Artinya:
- DTO adalah kontrak API
- Swagger adalah single source of truth
- Validasi dan dokumentasi harus jalan bersamaan
Ini bukan starter kit “paling fleksibel”, tapi opinionated — dan itu sengaja.
Karena di dunia nyata, tim butuh:
- Konsistensi
- Kejelasan
- Standar yang bisa diikuti
Struktur Project yang Mendukung Dokumentasi
Struktur project sangat berpengaruh pada kualitas dokumentasi.
Di starter kit ini:
- Setiap resource punya folder sendiri
- DTO dipisahkan dengan jelas
- Common response & decorator dikumpulkan
Tujuannya sederhana:
Developer baru bisa paham API hanya dari struktur folder + Swagger UI.
Dokumentasi tidak boleh terasa “terpisah” dari kode.
Swagger Setup: Cukup, Tidak Berlebihan
Swagger di-setup langsung di main.ts:
- Global prefix (/api)
- API versioning (/v1)
- Satu endpoint dokumentasi
Tidak ada konfigurasi berlebihan.
Kenapa?
Karena fokusnya bukan di setup, tapi di bagaimana Swagger merepresentasikan API kita.
Swagger hanyalah alat. Nilainya ada di cara kita menggunakannya.
DTO Bukan Cuma untuk Validasi
Ini bagian paling penting dari starter kit ini.
DTO digunakan sebagai:
- Validation schema
- Swagger schema
- API contract
Dengan @ApiProperty, kita bisa:
- Menentukan example
- Menjelaskan field
- Menunjukkan enum & optional field
Hasilnya:
- Frontend tidak perlu tanya
- QA tidak perlu nebak
- API lebih mudah dikembangkan
DTOs are not just validation tools — they are communication tools.
Konsistensi Response Itu Penting (Banget)
Salah satu hal paling menyebalkan bagi frontend adalah:
- Response yang beda-beda
- Error yang tidak konsisten
- Message yang tidak bisa diprediksi
Starter kit ini menggunakan format response standar:
- success
- message
- data
Semua response — sukses maupun error — mengikuti pola yang sama.
Swagger mendokumentasikan ini secara eksplisit.
Siapa yang Cocok Menggunakan Starter Kit Ini?
Starter kit ini cocok untuk:
- Backend developer yang ingin API rapi sejak awal
- Frontend developer yang ingin kontrak API jelas
- Team kecil–menengah
- Startup yang ingin scale tanpa chaos
Kalau kamu sering berpikir:
“Nanti aja dokumentasinya, sekarang fitur dulu”
Starter kit ini justru memaksa kamu berhenti berpikir seperti itu.
Menuju Starter Kit Selanjutnya
Swagger hanyalah fondasi.
Di artikel selanjutnya, starter kit ini akan dikembangkan dengan:
- Authentication (JWT)
- Authorization (RBAC)
- Database (Prisma)
Tanpa:
- Merusak kontrak API
- Mengubah dokumentasi
- Membuat frontend bingung
Penutup
API yang baik tidak ditemukan secara tidak sengaja.
API yang baik dirancang, didokumentasikan, dan dikomunikasikan.
NestJS + Swagger, jika digunakan dengan benar, bisa menjadi fondasi yang sangat kuat untuk itu.
Jika kamu tertarik:
- Repo starter kit ini tersedia di GitHub NestJs-Starter-Kits
- Feel free untuk fork, star, atau beri feedback
Di artikel berikutnya, kita akan lanjut ke NestJS + JWT Authentication — tanpa mengorbankan kejelasan API.
🚀 Happy building.