Scalar

Scalar bietet eine einfache Möglichkeit, mit Hono eine ansprechend gestaltete API-Referenz auf Basis eines OpenAPI-/Swagger-Dokuments anzuzeigen.

Installation

npm install @scalar/hono-api-reference

Verwendung

Richte Zod OpenAPI Hono oder Hono OpenAPI ein und übergib die konfigurierte URL an die Middleware 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

Themes

Die Middleware verwendet standardmäßig ein eigenes Hono-Theme. Für ein anderes Erscheinungsbild setze theme auf eines der vordefinierten Themes — alternate, default, moon, purple, solarized, bluePlanet, deepSpace, saturn, kepler, mars oder laserwave — oder auf none, um ohne Theme zu beginnen. Alle Themes bieten ein helles und ein dunkles Farbschema.

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

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

Eigener Seitentitel

Es gibt eine weitere Option, um den Seitentitel festzulegen:

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

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

Eigenes CDN

Du kannst ein eigenes CDN verwenden. Der Standardwert ist https://cdn.jsdelivr.net/npm/@scalar/api-reference.

Du kannst das CDN auch auf eine bestimmte Version festlegen, indem du sie in der CDN-Zeichenfolge angibst, zum Beispiel https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.28.

Alle verfügbaren CDN-Versionen findest du hier.

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',
  })
)

Markdown für LLMs

Wenn du eine Markdown-Version der API-Referenz für LLMs erstellen möchtest, installiere @scalar/openapi-to-markdown:

npm install @scalar/openapi-to-markdown

Füge dann eine zusätzliche Route dafür hinzu:

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

Wenn du Zod OpenAPI Hono verwendest, kannst du alternativ so vorgehen:

// 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)
})