Belajar HonoJS - OpenAPI & API Documentation

#Pendahuluan

Setelah di episode 14 kita mengimplementasikan WebSocket, pada episode ini kita akan memahami OpenAPI — standar untuk mendokumentasikan API yang memungkinkan client dan tools lain memahami struktur endpoint tanpa membaca source code.

#Swagger/OpenAPI Auto-Generation

#Setup Swagger UI

Install Swagger UI

bun add @hono/swagger-ui

Setup Swagger UI

import { Hono } from 'hono'
import { swaggerUI } from '@hono/swagger-ui'
 
const app = new Hono()
 
app.get('/ui', swaggerUI({ url: '/openapi.json' }))

Akses Swagger UI di http://localhost:8787/ui.

#hono-openapi untuk Spec Generation

Install hono-openapi

bun add hono-openapi

Generate OpenAPI spec

import { Hono } from 'hono'
import { openAPI } from 'hono-openapi'
 
const app = new Hono()
 
app.doc('/openapi.json', {
  openapi: '3.0.0',
  info: {
    title: 'My API',
    version: '1.0.0',
  },
})

#Customizing OpenAPI Metadata

#Metadata Lengkap

OpenAPI metadata lengkap

app.doc('/openapi.json', {
  openapi: '3.0.0',
  info: {
    title: 'User Management API',
    version: '2.0.0',
    description: 'API untuk mengelola user dan autentikasi',
    contact: {
      name: 'API Support',
      email: 'support@example.com',
    },
  },
  servers: [
    { url: 'http://localhost:8787', description: 'Development' },
    { url: 'https://api.example.com', description: 'Production' },
  ],
  components: {
    securitySchemes: {
      bearerAuth: {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
      },
    },
  },
})

#Zod Schema untuk OpenAPI

Gunakan Zod schema untuk generate OpenAPI spec otomatis dari validasi:

Zod schema → OpenAPI spec

import { z } from 'zod'
 
const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
})
 
// Schema yang sama untuk validasi request dan dokumentasi
app.post('/user', zValidator('json', userSchema), handler)

#Export OpenAPI Spec

Export spec ke file

import { write } from 'bun'
 
const spec = await fetch('http://localhost:8787/openapi.json').then(r => r.json())
await write('openapi.json', JSON.stringify(spec, null, 2))

Spec yang dihasilkan bisa digunakan untuk:

Postman: import collection dari OpenAPI spec.
Code generators: generate client SDK dari spec.
CI/CD: validasi spec di pipeline.

Tip

Gunakan Zod atau Valibot schema untuk generate OpenAPI spec otomatis. Schema yang sama digunakan untuk validasi request dan dokumentasi — single source of truth yang mengurangi duplikasi.

#Penutup

Pada episode 15 ini, kalian telah memahami cara auto-generate dokumentasi API dengan Swagger dan OpenAPI di Hono.

Inti yang harus dibawa pulang:

@hono/swagger-ui untuk Swagger UI interaktif.
hono-openapi untuk OpenAPI 3.0 spec generation.
Metadata: title, version, description, servers, security schemes.
Zod schema sebagai single source of truth untuk validasi dan dokumentasi.

Di episode 16 selanjutnya kita akan memahami performance optimization di edge — benchmarking, tiny preset, response caching, dan profiling di Cloudflare Workers. Sampai jumpa di episode 16!