Part 18 - Dokumentasi API (Swagger/OpenAPI)

API kita sekarang punya cukup banyak endpoint — auth, post, kategori, upload. Menjelaskan semuanya lewat dokumen terpisah gampang basi begitu ada perubahan kode. Di part ini kita pakai swaggo untuk generate dokumentasi OpenAPI langsung dari comment di source code, lengkap dengan UI interaktif untuk mencoba tiap endpoint dari browser.

Instalasi

Install CLI swag (tool generator, bukan dependency project):

go install github.com/swaggo/swag/cmd/swag@latest

Tambahkan library runtime untuk menyajikan Swagger UI di Fiber:

go get github.com/swaggo/swag github.com/swaggo/fiber-swagger

Anotasi Info Umum API

Swag membaca comment khusus berformat @tag value di atas fungsi tertentu. Tambahkan blok info umum di atas buildApp di main.go:

// @title						Blogfiber API
// @version					1.0
// @description				REST API blog sederhana - hasil dari seri Tutorial GoFiber Dasar.
// @host						localhost:3000
// @BasePath					/api/v1
// @securityDefinitions.apikey	BearerAuth
// @in							header
// @name						Authorization
// @description				Ketik "Bearer" diikuti spasi lalu access token JWT. Contoh: "Bearer eyJhbGc..."
func buildApp(db *gorm.DB) *fiber.App {

@securityDefinitions.apikey BearerAuth mendefinisikan skema autentikasi yang nanti dipakai ulang di endpoint yang butuh token.

Anotasi per Endpoint

Setiap handler diberi comment block persis di atasnya (swag membaca comment yang menempel langsung ke fungsi). Contoh untuk PostHandler.Create:

// Create godoc
//
//	@Summary	Buat post baru
//	@Tags		posts
//	@Accept		json
//	@Produce	json
//	@Security	BearerAuth
//	@Param		request	body	postRequest	true	"Data post"
//	@Success	201	{object}	map[string]interface{}
//	@Failure	401	{object}	map[string]interface{}
//	@Failure	422	{object}	map[string]interface{}
//	@Router		/posts [post]
func (h *PostHandler) Create(c *fiber.Ctx) error {

Dan untuk endpoint yang menerima file upload, UploadThumbnail:

// UploadThumbnail godoc
//
//	@Summary	Upload thumbnail post
//	@Description	Hanya pemilik post, format jpg/jpeg/png, maksimal 2MB
//	@Tags		posts
//	@Accept		multipart/form-data
//	@Produce	json
//	@Security	BearerAuth
//	@Param		id			path		int		true	"Post ID"
//	@Param		thumbnail	formData	file	true	"File gambar"
//	@Success	200	{object}	map[string]interface{}
//	@Failure	422	{object}	map[string]interface{}
//	@Router		/posts/{id}/thumbnail [post]
func (h *PostHandler) UploadThumbnail(c *fiber.Ctx) error {

Pola yang sama diterapkan ke semua handler: Index/Show (publik, tanpa @Security), Update/Delete (pakai @Security BearerAuth), serta seluruh endpoint di AuthHandler dan CategoryHandler. @Param request body <TypeName> merujuk ke struct request yang sudah ada (postRequest, registerRequest, dst) — swag otomatis membaca field dan tag json/validate dari struct itu untuk menghasilkan skema.

Generate Dokumentasi

Jalankan dari root project:

swag init -g main.go --output ./docs

Perintah ini membaca semua comment @... di kode, lalu menghasilkan folder docs/ berisi docs.go, swagger.json, dan swagger.yaml. docs.go perlu di-import (dengan _, blank import) supaya isinya ter-register ke Swagger UI:

import (
	_ "blogfiber/docs"
	// ...
)

Setiap kali menambah/mengubah anotasi di handler, jalankan ulang swag init supaya dokumentasi ikut ter-update — ini bukan proses otomatis saat go build.

Menyajikan Swagger UI

Tambahkan route di buildApp:

app.Get("/swagger/*", swagger.WrapHandler)

Testing

Jalankan server, lalu buka http://localhost:3000/swagger/index.html di browser — akan muncul halaman Swagger UI interaktif, berisi semua endpoint terorganisir per tag (auth, posts, categories), lengkap dengan form untuk mencoba tiap endpoint langsung dari browser (termasuk tombol "Authorize" untuk memasukkan Bearer token).

Verifikasi juga lewat terminal bahwa spec JSON-nya valid:

curl http://127.0.0.1:3000/swagger/doc.json | python3 -m json.tool

Semua endpoint yang sudah kita bangun sepanjang seri ini sekarang punya dokumentasi interaktif yang otomatis tetap sinkron dengan kode — selama anotasinya dijaga konsisten setiap kali menambah endpoint baru. Di part berikutnya, part terakhir yang berisi kode, kita siapkan project ini untuk deploy pakai Docker dan VPS.