HomeAboutProjectsBlogs

Bagaimana openapi.json yang Rapi Menyelamatkan Kesehatan Jiwa Saya sebagai Pengembang Frontend

Tanggal Publish: 2025-10-21

Saya dulu berpikir bahwa menjaga frontend dan backend tetap sinkron hanyalah bagian dari pekerjaan — seperti konflik penggabungan (merge conflicts) atau console log yang terlupakan. Namun, suatu hari, saat beralih antara dua proyek saya (satu untuk backend, satu untuk frontend), saya menyadari sesuatu: sebagian besar bug saya bukanlah kesalahan logika — melainkan kesalahan komunikasi.

Penderitaan Dua Dunia

Pengaturan saya cukup standar. Backend berada di folder sendiri, ditulis menggunakan NestJS dengan DTO yang indah, validasi, dan dokumentasi Swagger. Frontend berada terpisah — sebuah proyek Next.js yang mengambil data dari endpoint tersebut. Semuanya berjalan baik… sampai semuanya kacau. Setiap kali tim backend (yang biasanya hanya saya dengan peran berbeda) mengubah DTO — menambahkan field baru, mengganti nama kunci, mengubah tipe respons — frontend mulai menghasilkan error misterius. Itu seperti bermain whack-a-mole: 

  • Satu endpoint tiba-tiba mengembalikan user_name alih-alih username. 
  • Field bersarang berpindah dari data.details ke data.info.details. 
  • Respons untuk GET /exercise/:id berubah bentuk setelah refaktor. Dan bagian terburuknya? Frontend tidak tahu bahwa perubahan ini terjadi. Saya harus membuka Swagger, memeriksa respons secara manual, memperbarui tipe TypeScript, memperbaiki hook, dan berharap tidak ada yang terlewat. Saat itulah saya menyadari sesuatu yang penting: Masalahnya bukan pada kode — melainkan pada kontrak antara backend dan frontend.

Momen "Aha"

Suatu malam, setelah sesi debugging “mengapa-tipe-ini-undefined”, saya membuka openapi.json yang dihasilkan secara otomatis oleh NestJS. Itu indah. Setiap rute, setiap DTO, setiap skema — dijelaskan dengan sempurna dalam satu file. Saat itulah saya tersadar: Mengapa saya memperbarui tipe secara manual padahal backend sudah mengetahui semuanya? Backend secara harfiah mendeskripsikan dirinya sendiri dalam openapi.json ini. Yang perlu saya lakukan hanyalah membuat frontend mendengarkan.

Membangun Jembatan

Jadi, saya membuat CLI kecil. Awalnya, itu hanya skrip yang mengurai openapi.json dan menghasilkan tipe TypeScript. Lalu saya tambahkan fungsi API. Kemudian hook React Query. Dan sebelum saya sadari, itu menjadi generator layanan frontend yang lengkap. CLI membaca skema OpenAPI dari backend dan menghasilkan sesuatu seperti ini: 

services-generated/
    exercise/
       exercise.ts
       index.ts
       types.d.ts
       use-exercise.ts

Setiap folder mewakili sumber daya API, seperti exercise atau user. Setiap file memiliki peran spesifik: 

  • exercise.ts → Panggilan API (misalnya, getExercise, createExercise) 
  • types.d.ts → Antarmuka TypeScript yang dihasilkan otomatis dari DTO 
  • use-exercise.ts → Hook React siap pakai yang didukung oleh React Query 
  • index.ts → Mengekspor semuanya dengan rapi Tidak ada pekerjaan manual. Tidak ada tipe yang tidak cocok. Cukup jalankan CLI, dan semuanya diperbarui secara otomatis.

Keajaiban OpenAPI yang Rapi

Di sinilah ceritanya menjadi menarik. Seluruh sistem bergantung pada satu hal: openapi.json yang bersih dan terstruktur dengan baik. Jika file OpenAPI Anda berantakan — dengan skema yang hilang, tipe any yang longgar, atau penamaan yang tidak konsisten — generator akan gagal. Jadi, saya mulai memperlakukan openapi.json sebagai satu-satunya sumber kebenaran. Bukan sekadar “dokumentasi”, tetapi sebagai kontrak yang mendefinisikan bahasa antara backend dan frontend. Dan ketika kontrak itu bersih, segalanya menjadi mudah: 

  • Keamanan tipe didapatkan secara gratis. 
  • Kode frontend diperbarui dalam hitungan detik setelah perubahan backend. 
  • Pengembang baru dapat menjelajahi file yang dihasilkan dan langsung memahami API. 
  • Bug yang disebabkan oleh ketidaksesuaian API langsung hilang.

Hasilnya

Sekarang, ketika saya membuat perubahan di backend, yang saya lakukan hanyalah: 

  1. Regenerasi openapi.json (NestJS melakukannya secara otomatis). 
  2. Jalankan: bun run generate:service

Selesai. Frontend langsung memiliki hook, tipe, dan metode layanan terbaru — sepenuhnya sinkron dengan backend. Tidak perlu lagi menebak seperti apa DTO itu. Tidak ada lagi kontrak yang rusak. Tidak ada lagi momen “mengapa-ini-undefined” jam 2 pagi.

Pelajaran

Kita sering menganggap OpenAPI sebagai sesuatu yang dihasilkan di akhir — dokumentasi tambahan untuk pengguna eksternal. Tapi itu jauh lebih kuat ketika Anda membalikkan perspektifnya. openapi.json yang bersih bukanlah produk sampingan dari backend Anda. Itu adalah jembatan antara backend dan frontend — kontrak hidup yang dihasilkan otomatis dan dapat mendorong seluruh alur pengembangan Anda. Begitu Anda mulai melihatnya seperti itu, semuanya berubah.

Penutup

Sekarang, setiap proyek yang saya buat — sekecil apa pun — dimulai dengan komitmen untuk struktur OpenAPI yang bersih. Karena sekarang saya tahu: Semakin konsisten skema API Anda, semakin besar kebebasan frontend Anda untuk berkembang. Dan mungkin bagian terbaiknya? Ketika saya mengubah DTO di backend, saya tidak lagi takut. Saya hanya tersenyum, regenerate, dan terus membangun.