Belajar ElysiaJS - 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, request, dan response tanpa membaca source code.

#Swagger/OpenAPI Auto-Generation

#Setup Swagger

Install Swagger plugin

bun add @elysiajs/swagger

Setup Swagger UI

import { Elysia } from 'elysia'
import swagger from '@elysiajs/swagger'
 
const app = new Elysia()
  .use(swagger({
    documentation: {
      info: {
        title: 'My API',
        version: '1.0.0',
        description: 'API documentation untuk aplikasi saya',
      },
    },
  }))
  .listen(3000)

Akses Swagger UI di http://localhost:3000/swagger — halaman interaktif di mana kalian bisa melihat semua endpoint dan mencobanya langsung.

#Customizing OpenAPI Metadata

#Metadata di Level App

OpenAPI metadata lengkap

app.use(swagger({
  documentation: {
    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:3000', description: 'Development' },
      { url: 'https://api.example.com', description: 'Production' },
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
        },
      },
    },
  },
}))

#Detail per Route

Gunakan detail di route options untuk menambahkan deskripsi:

Detail per route untuk dokumentasi

.get('/users', getUsersHandler, {
  detail: {
    summary: 'Get all users',
    description: 'Mengembalikan daftar semua user dengan pagination',
    tags: ['Users'],
  }
})
.post('/users', createUserHandler, {
  detail: {
    summary: 'Create new user',
    description: 'Membuat user baru dengan nama dan email',
    tags: ['Users'],
  }
})

#Export OpenAPI Spec

Ekspor spec untuk konsumsi external tools:

Export OpenAPI spec ke file

import { write } from 'bun'
 
const spec = app.swagger()
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 TypeBox schema untuk generate OpenAPI spec otomatis. Schema yang sama digunakan untuk validasi request dan dokumentasi — single source of truth.

#Penutup

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

Inti yang harus dibawa pulang:

Plugin @elysiajs/swagger menghasilkan Swagger UI di /swagger.
Metadata: title, version, description, servers, security schemes.
Detail per route: summary, description, tags untuk dokumentasi terstruktur.
Export OpenAPI spec untuk konsumsi external tools.

Di episode 16 selanjutnya kita akan memahami performance optimization dan profiling — benchmarking, optimization techniques, profiling dengan Bun, dan caching strategy. Sampai jumpa di episode 16!