Hono OpenAPI

hono-openapi est un middleware qui génère automatiquement la documentation OpenAPI de votre API Hono. Il s’intègre aux bibliothèques de validation comme Zod, Valibot, ArkType et TypeBox, ainsi qu’à toutes celles qui prennent en charge Standard Schema.

🛠️ Installation

Installez le paquet avec votre bibliothèque de validation préférée et ses dépendances :

npm install hono-openapi @hono/standard-validator

Dans ce guide, nous utiliserons valibot

npm install valibot @valibot/to-json-schema

Pour en savoir plus sur l’installation, consultez https://honohub.dev/docs/openapi#installation

---

🚀 Premiers pas

1. Définir vos schémas

Définissez vos schémas de requête et de réponse avec votre bibliothèque de validation préférée. Voici un exemple avec Valibot :

import * as v from 'valibot'

const querySchema = v.object({
  name: v.optional(v.string()),
})

const responseSchema = v.string()

---

2. Créer des routes

Utilisez describeRoute pour documenter et valider les routes :

import { Hono } from 'hono'
import { describeRoute, resolver, validator } from 'hono-openapi'

const app = new Hono()

app.get(
  '/',
  describeRoute({
    description: 'Say hello to the user',
    responses: {
      200: {
        description: 'Successful response',
        content: {
          'text/plain': { schema: resolver(responseSchema) },
        },
      },
    },
  }),
  validator('query', querySchema),
  (c) => {
    const query = c.req.valid('query')
    return c.text(`Hello ${query?.name ?? 'Hono'}!`)
  }
)

Remarque :
Lorsque vous utilisez validator() de hono-openapi, toute validation ajoutée pour query, json, param ou form est automatiquement incluse dans le schéma de requête OpenAPI.
Il n’est pas nécessaire de définir manuellement les paramètres de requête dans describeRoute().

---

3. Générer la spécification OpenAPI

Ajoutez un point de terminaison pour votre document OpenAPI :

import { openAPIRouteHandler } from 'hono-openapi'

app.get(
  '/openapi',
  openAPIRouteHandler(app, {
    documentation: {
      info: {
        title: 'Hono API',
        version: '1.0.0',
        description: 'Greeting API',
      },
      servers: [
        { url: 'http://localhost:3000', description: 'Local Server' },
      ],
    },
  })
)

---

Pour aller plus loin, consultez notre documentation : https://honohub.dev/docs/openapi