Honoを使ってローカルでAPIドキュメントを生成する

今回の記事では以下のようにHello Worldを返すだけのシンプルなAPIを作成してそのAPIドキュメントを生成していきます。

import { Hono } from 'hono'

const app = new Hono()

app.get('/hellp', (c) => {
  return c.text('Hello, world!')
})

export default app

通常であれば、Honoクラスからインスタンスを生成しますが、今回は@hono/zod-openapiを使用するためまずはこれらをインストールしましょう。

npm install @hono/zod-openapi
npm install @hono/swagger-ui

そして、OpenAPIHonoクラスからインスタンスを生成します。OpenAPIHonoはOpenAPI ドキュメント生成に対応した拡張版のHonoクラスです。このクラスを使うことで app.openapi(...) や app.doc(...) などopenapiに対応した機能が使えるようになります。

import { Hono } from 'hono'

const app = new OpenAPIHono()

app.get('/hello', (c) => {
  return c.text('Hello, world!')
})

export default app

createRouteの定義

createRoute() は @hono/zod-openapi が提供する関数で、OpenAPI ドキュメントと Hono のルーティング定義を同時に行うためのものです。通常、API定義を書くときは次のように2つのことを別々に書きます：

1. Honoでのルーティング定義
2. OpenAPI（Swagger）のルーティング定義

createRoute()を使うことでこれらを1回の記述で対応できるようになります。さらにopenapi()を使用して、定義したルーティングをHonoで定義されたエンドポイントとハンドラに登録します。

import { OpenAPIHono, createRoute } from '@hono/zod-openapi'
import { z } from 'zod'

const app = new OpenAPIHono()

// OpenAPI 対応のルートを定義
app.openapi(
  createRoute({
    method: 'get',
    path: '/hello',
    description: 'シンプルな Hello World API',
    tags: ['Sample'],
    responses: {
      200: {
        description: '成功時のレスポンス',
        content: {
          'text/plain': {
            schema: z.string(),
            example: 'Hello, world!',
          },
        },
      },
    },
  }),
  async (c) => {
    return c.text('Hello, world!')
  }
)

export default app

Swagger UIでドキュメントが見れるように設定する

app.openapi() で定義した API を Swagger UI で見られるようにするには、以下のようにコードを書きます。これによりapp.openapi(...) で登録したルーティングの情報を元に自動生成されるJSON 定義が /v1/spec/json に出力されます。そして、/v1/specのパスでSwagger UIが閲覧できるようになります。

app.get('/v1/spec', swaggerUI({ url: '/v1/spec/json' }))
app.doc('/v1/spec/json', {
  openapi: '3.0.0',
  info: {
    title: 'My API',
    version: '1.0.0',
    description: 'シンプルなサンプルAPI',
  },
})

ローカルサーバーを立ててSwagger UIを確認する

今回作ったソースコードの全体が以下のようになります。

import { OpenAPIHono, createRoute } from '@hono/zod-openapi'
import { swaggerUI } from '@hono/swagger-ui'
import { z } from 'zod'

const app = new OpenAPIHono()

app.openapi(
  createRoute({
    method: 'get',
    path: '/hello',
    description: 'Hello World endpoint',
    tags: ['Example'],
    responses: {
      200: {
        description: '成功レスポンス',
        content: {
          'text/plain': {
            schema: z.string(),
            example: 'Hello, world!',
          },
        },
      },
    },
  }),
  (c) => c.text('Hello, world!')
)

// Swagger UI 設定
app.get('/v1/spec', swaggerUI({ url: '/v1/spec/json' }))

app.doc('/v1/spec/json', {
  openapi: '3.0.0',
  info: {
    title: 'My API',
    version: '1.0.0',
    description: 'シンプルなサンプルAPI',
  },
})

export default app

別のファイルに@hono/node-server を使用して、Swagger UIを立ち上げるサーバーの記述を行います。

import { serve } from '@hono/node-server'
import  app from './routes'

serve(app, (info) => {
  console.log(`Swagger UI available at http://localhost:${info.port}/v1/spec`)
})

 % npx ts-node server.ts
Swagger UI available at http://localhost:3000/v1/spec

そして、コマンドによりサーバーを立ち上げることでローカル上でAPI定義が確認できるようになりました。