API Spec dan Daftar Endpoint

Spesifikasi API repository ini berada di satu berkas, api/api-spec.json:1-12¹. Berkas itu memakai openapi 3.0.3, info.title "Golang Clean Architecture", info.version "1.0.0", dan satu servers ke http://localhost:3000. Blok paths mendeklarasikan lima belas operasi pada lima path, terbagi rata ke tiga tag: User API, Contact API, dan Address API (api/api-spec.json:13-1060²).

Pemetaan tag ke handler

Satu tag di api/api-spec.json berpasangan dengan satu controller di internal/delivery/http. Tag User API berisi lima operasi yang dilayani UserController, tag Contact API lima operasi ContactController, dan tag Address API lima operasi AddressController (internal/delivery/http/route/route.go:17-43³).

graph LR
  TU["tag: User API"] --> UC["UserController"]
  TC["tag: Contact API"] --> CC["ContactController"]
  TA["tag: Address API"] --> AC["AddressController"]
  TU --> RM["model.RegisterUserRequest"]
  TC --> SM["model.SearchContactRequest"]
  TA --> DM["model.CreateAddressRequest"]
  UC --> UM["model.UserResponse"]
  CC --> CM["model.ContactResponse"]
  AC --> AM["model.AddressResponse"]
  style TU fill:#f59e0b,color:#000
  style TC fill:#f59e0b,color:#000
  style TA fill:#f59e0b,color:#000
  style UC fill:#2d7d46,color:#fff
  style CC fill:#2d7d46,color:#fff
  style AC fill:#2d7d46,color:#fff
  style RM fill:#8b5cf6,color:#fff
  style SM fill:#8b5cf6,color:#fff
  style DM fill:#8b5cf6,color:#fff
  style UM fill:#8b5cf6,color:#fff
  style CM fill:#8b5cf6,color:#fff
  style AM fill:#8b5cf6,color:#fff
%% fig: Tag API ke controller dan schema model
%% desc: Tiga tag OpenAPI memetakan ke tiga controller Fiber, dan tiap controller memakai satu pasangan schema request serta response dari package model.

Schema yang dipakai controller bisa dilacak ke package model. RegisterUserRequest mewajibkan id, name, dan password dengan batas max=100 (internal/model/user_model.go:15-19⁴), sama dengan daftar required di spesifikasi (api/api-spec.json:14-44⁵). UserResponse punya field token (internal/model/user_model.go:3-9⁶); field itu hanya muncul di response login (api/api-spec.json:146-158⁷). SearchContactRequest memuat Name, Email, Phone, Page, dan Size (internal/model/contact_model.go:31-38⁸), yang datang dari query parameter name, phone, email, page dengan default 1, dan size dengan default 10 (api/api-spec.json:369-411⁹). Untuk address, CreateAddressRequest memakai street, city, province, postal_code, dan country (internal/model/address_model.go:19-27¹⁰), persis seperti request body di spesifikasi (api/api-spec.json:668-691¹¹).

Daftar endpoint

Seluruh pasangan path dan handler di tabel di atas berasal dari route.go (internal/delivery/http/route/route.go:17-43³). Spesifikasi menulis path parameter dengan kurung kurawal, misalnya {contactId} dan {addressId} (api/api-spec.json:474-497¹²), sedangkan route.go memakai sintaks Fiber :contactId dan :addressId (internal/delivery/http/route/route.go:27-43¹³). Operasi address yang menyentuh satu alamat membawa dua path parameter sekaligus (api/api-spec.json:833-863¹⁴).

Operasi publik dan operasi bertoken

graph TD
  R["request HTTP"] --> S["RouteConfig.Setup"]
  S --> G["SetupGuestRoute"]
  S --> A["SetupAuthRoute"]
  G --> G1["POST /api/users"]
  G --> G2["POST /api/users/_login"]
  A --> MW["middleware.NewAuth"]
  MW --> OK["ctx.Locals auth"]
  MW --> NO["fiber.ErrUnauthorized"]
  OK --> H["13 route terproteksi"]
  style S fill:#f59e0b,color:#000
  style MW fill:#f59e0b,color:#000
  style G1 fill:#2d7d46,color:#fff
  style G2 fill:#2d7d46,color:#fff
  style OK fill:#2d7d46,color:#fff
  style H fill:#2d7d46,color:#fff
  style NO fill:#dc2626,color:#fff
%% fig: Pembagian route publik dan route bertoken
%% desc: Dua route didaftarkan sebelum middleware auth dipasang, sedangkan tiga belas route lain baru aktif setelah middleware memverifikasi header Authorization.

SetupGuestRoute mendaftarkan POST /api/users dan POST /api/users/_login sebelum c.App.Use(c.AuthMiddleware) dipasang, sehingga keduanya terbuka (internal/delivery/http/route/route.go:17-25¹⁵). Tiga belas route sisanya baru didaftarkan setelah middleware (internal/delivery/http/route/route.go:27-43¹³). Middleware membaca header lewat ctx.Get("Authorization", "NOT_FOUND") dan mengembalikan fiber.ErrUnauthorized ketika Verify gagal (internal/delivery/http/middleware/auth_middleware.go:10-24¹⁶).

Spesifikasi mengikuti pembagian itu dengan mengulang parameter header Authorization bertipe in: header dan required: true pada setiap operasi terproteksi, misalnya logout (api/api-spec.json:77-109¹⁷) dan get current user (api/api-spec.json:162-177¹⁸). Operasi register tidak punya blok parameters sama sekali (api/api-spec.json:14-44⁵).

Amplop response

Response sukses memakai model.WebResponse[T] dengan field data, paging (opsional), dan errors (opsional) (internal/model/model.go:3-19¹⁹). paging hanya dideklarasikan pada GET /api/contacts, dengan page, size, total_item, dan total_page (api/api-spec.json:449-465²⁰); bentuk itu sama dengan model.PageMetadata di berkas model yang sama (internal/model/model.go:3-19¹⁹).

⚠️ api/api-spec.json hanya mendeklarasikan responses 200, tanpa schema error, dan berkas ditutup tanpa blok components (api/api-spec.json:1059-1061²¹). Bentuk error sebenarnya ditentukan NewErrorHandler, yang mengembalikan body {"errors": ...} dengan status diambil dari *fiber.Error bila error itu bertipe demikian (internal/config/fiber.go:18-28²²). Beberapa description juga sisa salin-tempel: GET /api/users/_current masih tertulis "Success register new user" (api/api-spec.json:178-208²³).