Hono OpenAPI 소개

hono-openapi는 Hono API를 위한 자동 OpenAPI 문서 생성을 가능하게 하는 _미들웨어_다. 이 미들웨어는 Zod, Valibot, ArkType, TypeBox와 같은 검증 라이브러리와 통합되어 작동한다.

🛠️ 설치

선호하는 검증 라이브러리와 함께 패키지를 설치한다. 필요한 의존성도 함께 설치한다:

# Zod 사용 시
pnpm add hono-openapi @hono/zod-validator zod zod-openapi

# Valibot 사용 시
pnpm add hono-openapi @hono/valibot-validator valibot @valibot/to-json-schema

# ArkType 사용 시
pnpm add hono-openapi @hono/arktype-validator arktype

# TypeBox 사용 시
pnpm add hono-openapi @hono/typebox-validator @sinclair/typebox

---

🚀 시작하기

1. 스키마 정의하기

선호하는 검증 라이브러리를 사용해 요청과 응답 스키마를 정의한다. Valibot를 사용한 예제는 다음과 같다:

import * as v from 'valibot'

const querySchema = v.object({
  name: v.optional(v.string()),
})

const responseSchema = v.string()

2. 라우트 생성

라우트 문서화와 유효성 검사를 위해 describeRoute를 사용한다:

import { Hono } from 'hono'
import { describeRoute } from 'hono-openapi'
// 선호하는 유효성 검사 라이브러리를 위해 다음을 임포트할 수 있다
import {
  resolver,
  validator as vValidator,
} from 'hono-openapi/valibot'

const app = new Hono()

app.get(
  '/',
  describeRoute({
    description: '사용자에게 인사하기',
    responses: {
      200: {
        description: '성공적인 응답',
        content: {
          'text/plain': { schema: resolver(responseSchema) },
        },
      },
    },
  }),
  vValidator('query', querySchema),
  (c) => {
    const query = c.req.valid('query')
    return c.text(`안녕하세요 ${query?.name ?? 'Hono'}!`)
  }
)

3. OpenAPI 스펙 생성

OpenAPI 문서를 위한 엔드포인트를 추가한다:

import { openAPISpecs } from 'hono-openapi'

app.get(
  '/openapi',
  openAPISpecs(app, {
    documentation: {
      info: {
        title: 'Hono API',
        version: '1.0.0',
        description: 'Greeting API',
      },
      servers: [
        { url: 'http://localhost:3000', description: 'Local Server' },
      ],
    },
  })
)

🌐 API 문서 제공하기

OpenAPI 스펙을 시각화하기 위해 Swagger UI나 Scalar 같은 도구를 사용한다. Scalar를 활용한 예제는 다음과 같다:

import { apiReference } from '@scalar/hono-api-reference'

app.get(
  '/docs',
  apiReference({
    theme: 'saturn',
    spec: { url: '/openapi' },
  })
)

🔍 고급 기능

보안 정의 추가

app.get(
  '/openapi',
  openAPISpecs(app, {
    documentation: {
      components: {
        securitySchemes: {
          bearerAuth: {
            type: 'http',
            scheme: 'bearer', 
            bearerFormat: 'JWT',
          },
        },
      },
      security: [{ bearerAuth: [] }],
    },
  })
)

조건부로 라우트 숨기기

app.get(
  '/',
  describeRoute({
    // ...
    hide: process.env.NODE_ENV === 'production',
  }),
  (c) => c.text('Hidden Route')
)

응답 검증

app.get(
  '/',
  describeRoute({
    // ...
    validateResponse: true,
  }),
  (c) => c.text('검증된 응답')
)

---

더 많은 예제와 상세한 문서는 hono-openapi 저장소에서 확인할 수 있다.