Part 1 - Apa itu OpenAPI dan Kenapa Spec-First

Selamat datang di seri OpenAPI Spec-First untuk Go Developer. Di seri ini kita akan belajar mendesain dan membangun REST API dengan pendekatan spec-first: nulis kontrak API-nya dulu dalam bentuk file OpenAPI (YAML), baru generate kode Go dari kontrak itu — bukan sebaliknya.

Masalah yang Sering Terjadi

Pernah mengalami situasi ini?

• Frontend/mobile developer nebak-nebak bentuk response API karena dokumentasinya basi atau nggak ada sama sekali
• Postman collection yang dipakai tim udah nggak sinkron sama endpoint yang sebenarnya
• Endpoint berubah diam-diam (field dihapus, tipe data berubah) dan baru ketahuan pas production error
• Dokumentasi API ditulis manual setelah semua kode jadi, lalu nggak pernah di-update lagi

Semua ini akar masalahnya sama: dokumentasi API dianggap sebagai langkah terakhir, padahal seharusnya jadi langkah pertama.

Apa itu OpenAPI

OpenAPI Specification (dulu disebut Swagger) adalah standar format (YAML/JSON) untuk mendeskripsikan REST API secara lengkap dan presisi: endpoint apa saja yang ada, parameter apa yang diterima, bentuk request body, bentuk response, kode error yang mungkin terjadi — semuanya didefinisikan dalam satu file yang bisa dibaca manusia maupun mesin.

Karena bisa dibaca mesin, file OpenAPI ini bisa dipakai untuk:

• Generate dokumentasi interaktif (Swagger UI, Redoc) — tim lain bisa langsung coba endpoint dari browser
• Generate kode — types, interface handler, bahkan client SDK, otomatis dari spec
• Validasi — mengecek request/response sesuai kontrak sebelum kode ditulis
• Contract testing — memastikan implementasi tidak menyimpang dari kontrak yang disepakati

Code-First vs Spec-First

Ada dua pendekatan umum untuk menghasilkan dokumentasi OpenAPI dari sebuah API Go:

Code-first — nulis handler dan struct Go seperti biasa, lalu tempelkan comment/annotation di atas tiap handler (misalnya pakai swaggo/swag), lalu generate file YAML dari comment itu. Enak buat API yang sudah terlanjur jalan dan baru mau didokumentasikan.

Spec-first — nulis file YAML OpenAPI dulu sebagai kontrak, baru generate types + interface handler Go dari situ (pakai oapi-codegen). Handler tinggal implement interface yang sudah digenerate.

Seri ini fokus ke spec-first, karena:

1. Kontrak disepakati di awal — tim frontend/mobile/backend bisa kerja paralel begitu YAML-nya fix, tanpa saling nunggu
2. Compiler ikut menjaga kontrak — begini nanti bakal kelihatan di Part 4: begitu YAML berubah dan interface Go ikut berubah, handler yang belum disesuaikan akan gagal compile, bukan diam-diam salah di runtime
3. Satu sumber kebenaran — YAML adalah dokumentasi sekaligus kontrak sekaligus sumber generate kode; tidak ada dua tempat yang bisa saling nggak sinkron

Apa yang Akan Dibangun

Seri ini dibagi dua bagian:

Bagian 1 — Konsep umum (Part 1-5), pakai contoh "Notes API" yang berdiri sendiri (standalone, in-memory, tanpa database) supaya fokus ke mekanisme OpenAPI + oapi-codegen itu sendiri:

• Part 2: Anatomi file OpenAPI YAML
• Part 3: Ekosistem tools OpenAPI di Go
• Part 4: Generate dan jalankan kode dari spec
• Part 5: Validasi spec dan dokumentasi interaktif

Bagian 2 — Terapkan ke project hexagonal architecture nyata (Part 6-8), pakai boilerplate Go hexagonal architecture, menambahkan fitur Product API dari nol dengan workflow spec-first yang sudah dipelajari:

• Part 6: Dari spec generik ke pattern hexagonal
• Part 7: Wiring generated interface ke handler hexagonal
• Part 8: Full loop di real project — generate, jalankan, test

Semua kode di seri ini sungguhan dibangun dan ditest — bukan potongan kode ilustratif. Project "Notes API" dan "Product API" yang dipakai sepanjang seri ini sudah di-build, di-generate, dan di-curl satu per satu untuk memastikan setiap response yang ditampilkan di artikel ini benar-benar keluar dari server yang jalan, bukan ditulis manual.

Di part selanjutnya, kita mulai dengan hal paling dasar: struktur sebuah file OpenAPI YAML, dan apa makna tiap bagiannya.