标量

¥Scalar

标量 提供了一种简便的方法，可以使用 Hono 基于 OpenAPI/Swagger 文档渲染美观的 API 参考文档。

¥Scalar provides an easy way to render a beautiful API reference based on an OpenAPI/Swagger document with Hono.

安装

¥Installation

npm install @scalar/hono-api-reference

用法

¥Usage

设置 Zod OpenAPI Hono 或 Hono OpenAPI，并将配置的 URL 传递给 Scalar 中间件：

¥Set up Zod OpenAPI Hono or Hono OpenAPI and pass the configured URL to the Scalar middleware:

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

主题

¥Themes

中间件带有 Hono 的自定义主题。你可以使用 其他预定义功能主题 的某个版本（alternate、default、moon、purple、solarized），或者将其覆盖为 none。所有主题均提供浅色和深色配色方案。

¥The middleware comes with a custom theme for Hono. You can use one of the other predefined themes (alternate, default, moon, purple, solarized) or overwrite it with none. All themes come with a light and dark color scheme.

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

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

自定义页面标题

¥Custom page title

设置页面标题还有一个额外的选项：

¥There's one additional option to set the page title:

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

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

自定义 CDN

¥Custom CDN

你可以使用自定义 CDN，默认 CDN 为 https://cdn.jsdelivr.net/npm/@scalar/api-reference。

¥You can use a custom CDN, default is https://cdn.jsdelivr.net/npm/@scalar/api-reference.

你还可以通过在 CDN 字符串中指定版本号（例如 https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.28）来将 CDN 锁定到特定版本。

¥You can also pin the CDN to a specific version by specifying it in the CDN string like https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.28.

你可以在 此处 中找到所有可用的 CDN 版本。

¥You can find all available CDN versions here.

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 格式

¥Markdown for LLMs

如果你想创建 API 参考的 Markdown 版本（用于 LLM），请安装 @scalar/openapi-to-markdown：

¥If you want to create a Markdown version of the API reference (for LLMs), install @scalar/openapi-to-markdown:

npm install @scalar/openapi-to-markdown

并为其添加一条额外的路由：

¥And add an additional route for it:

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：

¥Or, if you are using 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)
})