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。

也可以在 CDN 字符串中指定版本，将 CDN 固定到特定版本，例如 https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.28。

所有可用的 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 使用的 Markdown 版 API 参考文档，请安装 @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)
})