Part 21 - Dokumentasi API (Swagger/OpenAPI)

Sampai part ini, API blog kita sudah punya banyak sekali endpoint — auth, post, comment, kategori, masing-masing dengan aturan validasi dan proteksinya sendiri. Kalau ada developer lain (atau kita sendiri, enam bulan dari sekarang) yang mau pakai API ini, mengandalkan ingatan atau baca kode satu-satu jelas tidak ideal. Di part ini kita akan menambahkan dokumentasi API interaktif menggunakan OpenAPI (Swagger).

Pendekatan yang Dipakai

Ada dua cara umum bikin dokumentasi OpenAPI di Go:

Annotation-based — pakai tool seperti swaggo/swag yang generate spec dari komentar di atas function controller. Powerful, tapi butuh CLI generator terpisah dan sedikit "magic".
Hand-written spec — kita tulis sendiri file openapi.json sesuai standar OpenAPI 3.0, lalu tinggal disajikan lewat Swagger UI.

Untuk tutorial ini kita pakai cara kedua — lebih transparan untuk dipelajari, dan tidak menambah dependency tooling baru. Kalau nanti project sudah lebih besar, migrasi ke pendekatan annotation-based sepenuhnya memungkinkan.

Menulis Spec OpenAPI

Buat file resources/openapi.json. Strukturnya mengikuti standar OpenAPI 3.0: info, servers, components (schema reusable & security scheme), dan paths (daftar endpoint).

Contoh potongan untuk endpoint Login:

{
  "openapi": "3.0.3",
  "info": {
    "title": "MyBlog API",
    "description": "REST API blog sederhana yang dibangun dengan Goravel Framework.",
    "version": "1.0.0"
  },
  "servers": [{ "url": "http://127.0.0.1:3000" }],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
    }
  },
  "paths": {
    "/login": {
      "post": {
        "tags": ["Auth"],
        "summary": "Login",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Berhasil login" },
          "401": { "description": "Kredensial salah" }
        }
      }
    }
  }
}

securitySchemes.bearerAuth didefinisikan sekali di components, lalu tinggal direferensikan di endpoint yang butuh autentikasi lewat "security": [{ "bearerAuth": [] }] — persis seperti endpoint POST /posts, POST /logout, DELETE /comments/{commentId}, dan endpoint terproteksi lainnya yang sudah kita buat sejak part-part sebelumnya.

Lengkapi spec ini untuk semua endpoint: /register, /refresh, /posts, /posts/{id}, /posts/{id}/comments, /comments/{commentId}, dan /categories.

Menyajikan Spec dan Swagger UI

Buat app/http/controllers/docs_controller.go:

package controllers

import (
	"github.com/goravel/framework/contracts/http"
	"github.com/goravel/framework/support/path"
)

type DocsController struct {
}

func NewDocsController() *DocsController {
	return &DocsController{}
}

func (r *DocsController) Spec(ctx http.Context) http.Response {
	return ctx.Response().File(path.Resource("openapi.json"))
}

func (r *DocsController) Index(ctx http.Context) http.Response {
	html := `<!doctype html>
<html>
<head>
	<title>MyBlog API Docs</title>
	<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.32.13/swagger-ui.css"
		integrity="sha384-tRpWwikYYdk1+1Mu0osh0Tz/Ay5xgS+s/Nf2Aa7GVAFtZLFdJlAbozfrq4g+xHBK"
		crossorigin="anonymous">
</head>
<body>
	<div id="swagger-ui"></div>
	<script src="https://unpkg.com/swagger-ui-dist@5.32.13/swagger-ui-bundle.js"
		integrity="sha384-PsJla434CobCNv3y1K4wRavOqkUAvwGEQEfbUmI98CCqqGCJsmuDsgIjM6ZQQODP"
		crossorigin="anonymous"></script>
	<script>
		window.onload = () => {
			window.ui = SwaggerUIBundle({
				url: '/docs/openapi.json',
				dom_id: '#swagger-ui',
			});
		};
	</script>
</body>
</html>`

	return ctx.Response().Data(http.StatusOK, "text/html; charset=utf-8", []byte(html))
}

Beberapa catatan:

Spec cukup mengembalikan file JSON mentah lewat ctx.Response().File(...) — tidak perlu parsing apapun di sisi Go, Swagger UI yang akan membaca dan merender spec-nya di browser.
Index mengembalikan halaman HTML minimal yang memuat Swagger UI dari CDN. Karena ini script pihak ketiga yang dimuat di halaman kita, kita sertakan atribut integrity (SRI hash) dan crossorigin="anonymous" — supaya browser menolak memuat file itu kalau isinya ternyata berbeda dari yang kita percaya (misalnya CDN diretas atau file-nya dimodifikasi di tengah jalan). Versi library juga dikunci ke angka pasti (5.32.13, bukan 5 mengambang) supaya hash SRI ini tidak pernah basi.

Menambahkan Route

docsController := controllers.NewDocsController()
facades.Route().Get("/docs", docsController.Index)
facades.Route().Get("/docs/openapi.json", docsController.Spec)

Kedua route ini publik — dokumentasi API memang wajarnya bisa diakses siapa saja tanpa perlu login.

Testing

Jalankan server, lalu buka http://127.0.0.1:3000/docs di browser. Halaman Swagger UI akan muncul, menampilkan semua endpoint terorganisir per tag (Auth, Posts, Comments, Categories), lengkap dengan tombol "Try it out" untuk langsung mencoba tiap endpoint dari browser — termasuk tombol "Authorize" untuk memasukkan Bearer token supaya bisa mencoba endpoint yang butuh autentikasi.

Penutup

Dokumentasi ini akan makin berguna seiring API terus berkembang — pastikan untuk selalu memperbarui openapi.json setiap kali ada endpoint baru atau field yang berubah, supaya dokumentasinya tidak basi. Di part terakhir seri ini, kita akan membahas cara men-deploy aplikasi Goravel kita ke server sungguhan menggunakan Docker.

Tags:

Mr Sugiarto

Developer

Bagian dari Series: Seri Tutorial Belajar Framework Goravel Rest API untuk Pemula

Overview Seri ini membahas cara membangun REST API menggunakan Goravel, framework web berbasis Golang yang terinspirasi dari Laravel. Materi mencakup...

Lihat Series Lengkap