Scalar

Scalar を使うと、Hono で OpenAPI／Swagger ドキュメントから美しい API リファレンスを簡単に表示できます。

インストール

npm install @scalar/hono-api-reference

使い方

Zod OpenAPI Hono または Hono OpenAPI を設定し、その URL を Scalar ミドルウェアに渡します。

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

const app = new Hono()

// Use the middleware to serve the Scalar API Reference at /scalar
app.get('/scalar', Scalar({ url: '/doc' }))

// Or with dynamic configuration
app.get(
  '/scalar',
  Scalar((c) => {
    return {
      url: '/doc',
      proxyUrl:
        c.env.ENVIRONMENT === 'development'
          ? 'https://proxy.scalar.com'
          : undefined,
    }
  })
)

export default app

テーマ

ミドルウェアは、デフォルトで Hono 独自のテーマを適用します。見た目を変えるには、theme に定義済みのテーマである alternate、default、moon、purple、solarized、bluePlanet、deepSpace、saturn、kepler、mars、laserwave のいずれかを指定します。none を指定すると、テーマなしの状態から始められます。すべてのテーマにはライトとダークの配色があります。

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

// Switch the theme (or pass other options)
app.get(
  '/scalar',
  Scalar({
    url: '/doc',
    theme: 'purple',
  })
)

ページタイトルの変更

ページタイトルを設定する追加オプションもあります。

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

// Set a page title
app.get(
  '/scalar',
  Scalar({
    url: '/doc',
    pageTitle: 'Awesome API',
  })
)

独自の CDN

独自の CDN を使用できます。デフォルトは https://cdn.jsdelivr.net/npm/@scalar/api-reference です。

https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.28 のように CDN の文字列にバージョンを指定して、特定のバージョンに固定することもできます。

利用可能な CDN のバージョンはこちらで確認できます。

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

app.get('/scalar', Scalar({ url: '/doc', pageTitle: 'Awesome API' }))

app.get(
  '/scalar',
  Scalar({
    url: '/doc',
    cdn: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest',
  })
)

LLM 向けの Markdown

LLM 向けに API リファレンスの Markdown 版を作成する場合は、@scalar/openapi-to-markdown をインストールします。

npm install @scalar/openapi-to-markdown

そのためのルートを追加します。

import { Hono } from 'hono'
import { createMarkdownFromOpenApi } from '@scalar/openapi-to-markdown'

const app = new Hono()

// Generate Markdown from your OpenAPI document
const markdown = await createMarkdownFromOpenApi(content)

/**
 * Register a route to serve the Markdown for LLMs
 *
 * Q: Why /llms.txt?
 * A: It's a proposal to standardise on using an /llms.txt file.
 *
 * @see https://llmstxt.org/
 */
app.get('/llms.txt', (c) => c.text(markdown))

export default app

Zod OpenAPI Hono を使っている場合は、次のようにします。

// Get the OpenAPI document
const content = app.getOpenAPI31Document({
  openapi: '3.1.0',
  info: { title: 'Example', version: 'v1' },
})

const markdown = await createMarkdownFromOpenApi(
  JSON.stringify(content)
)

app.get('/llms.txt', async (c) => {
  return c.text(markdown)
})