Part 3 - Ekosistem Tools OpenAPI di Go

Sebelum masuk ke generate kode di Part 4, kita kenalan dulu dengan beberapa tools OpenAPI yang umum dipakai di ekosistem Go, karena masing-masing punya filosofi yang berbeda.

1. swaggo/swag — Code-First

swaggo/swag bekerja dengan cara membaca comment annotation di atas kode Go yang sudah ada, lalu generate file swagger.json/docs.go dari situ.

// ListNotes godoc
// @Summary      Daftar notes
// @Tags         notes
// @Produce      json
// @Success      200  {object}  NotesResponse
// @Router       /notes [get]
func ListNotes(c *fiber.Ctx) error {
    // ...
}

Cocok untuk: API yang sudah terlanjur jalan dan baru mau didokumentasikan, atau tim yang lebih nyaman nulis kode dulu baru dokumentasi menyusul.

Trade-off: dokumentasi bisa menyimpang dari kode asli kalau annotation lupa di-update — karena sumber kebenarannya ada di kode, bukan di satu file spec yang terpisah.

2. oapi-codegen — Spec-First

oapi-codegen bekerja sebaliknya: baca file OpenAPI YAML, generate types Go + interface handler (ServerInterface) dari situ. Kode handler tinggal implement interface yang sudah jadi.

oapi-codegen -package notesapi -generate types,fiber,spec \
  api/openapi/notes-api.yaml > internal/generated/notesapi/server.gen.go

Mendukung beberapa web framework populer di Go lewat flag -generate: chi, echo, fiber, gin, gorilla, atau cuma types kalau mau pakai router sendiri.

Cocok untuk: tim yang mau kontrak API disepakati di awal, API baru yang dibangun dari nol, atau microservice yang kontraknya perlu disinkronkan antar tim/service.

Trade-off: ada satu langkah ekstra (generate) tiap kali spec berubah — tapi ini justru fiturnya, bukan bug (lihat Part 1: compiler ikut menjaga kontrak).

Ini yang dipakai sepanjang seri ini.

3. go-swagger — Spec-First, Lebih Berat

go-swagger juga spec-first, tapi lebih besar cakupannya: bisa generate full server (bukan cuma interface), client SDK, bahkan bisa extract spec dari kode lewat swagger generate spec. Mendukung OpenAPI 2.0 (Swagger) secara native dan OpenAPI 3.0 lewat konversi.

Cocok untuk: project besar yang butuh generate client SDK sekaligus server, atau yang sudah pakai Swagger 2.0 dari lama.

Trade-off: lebih banyak "magic" dan konvensi yang harus diikuti, kurva belajarnya lebih curam dibanding oapi-codegen yang lebih minimal.

Kenapa oapi-codegen untuk Seri Ini

Tiga alasan:

1. Output-nya minimal dan predictable — cuma generate types + interface, sisanya (service, repository, business logic) tetap kita yang tulis dengan arsitektur yang kita pilih sendiri (hexagonal, seperti yang akan kita pakai di Part 6-8).
2. Dukungan Fiber langsung — relevan karena stack Go di seri-seri IndoKoding lain (GoFiber Dasar, GoHexaClean) juga pakai Fiber.
3. Satu binary CLI, tanpa dependency framework tambahan — gampang diinstal (go install) dan dipakai di CI/CD atau pre-commit hook.

Instalasi

go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest

Setelah ini, binary oapi-codegen tersedia di $GOPATH/bin (biasanya ~/go/bin), siap dipakai seperti contoh perintah di atas.

Di Part 4, kita jalankan generate ini sungguhan terhadap notes-api.yaml yang sudah kita tulis di Part 2, lihat apa isi kode yang dihasilkan, dan mulai mengimplementasikan handler-nya.