Scalar

Scalar permet d’afficher facilement une élégante documentation de référence d’API fondée sur un document OpenAPI/Swagger avec Hono.

Installation

npm install @scalar/hono-api-reference

Utilisation

Configurez Zod OpenAPI Hono ou Hono OpenAPI, puis transmettez l’URL configurée au 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

Thèmes

Le middleware applique par défaut un thème Hono personnalisé. Pour changer son apparence, définissez theme sur l’un des thèmes prédéfinis — alternate, default, moon, purple, solarized, bluePlanet, deepSpace, saturn, kepler, mars ou laserwave — ou sur none pour partir d’une page vierge. Tous les thèmes proposent des variantes claire et sombre.

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

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

Titre de page personnalisé

Une option supplémentaire permet de définir le titre de la page :

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

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

CDN personnalisé

Vous pouvez utiliser un CDN personnalisé ; la valeur par défaut est https://cdn.jsdelivr.net/npm/@scalar/api-reference.

Vous pouvez aussi fixer une version précise dans l’URL du CDN, par exemple https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.28.

Toutes les versions disponibles sur le CDN sont répertoriées ici.

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 pour les LLM

Pour créer une version Markdown de la référence de l’API (pour les LLM), installez @scalar/openapi-to-markdown :

npm install @scalar/openapi-to-markdown

Puis ajoutez une route supplémentaire :

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

Ou, si vous utilisez 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)
})