chanfana

OpenAPI 3 and 3.1 schema generator and validator for Hono, itty-router and more!

Documentation: chanfana.pages.dev

Source Code: github.com/cloudflare/chanfana

chanfana (previously known as itty-router-openapi) is a library that adds
OpenAPI schema generation and validation to any router (
Hono, itty-router, etc), meant to be a
powerful and lightweight
library for Cloudflare Workers but runs on any runtime supported by the base router.

The key features are:

- OpenAPI 3 and 3.1 schema generator and validator
- Fully written in typescript
- Class-based endpoints
- Query, Path, Headers, and Body typescript inference, see Parameters and Request Validation
- Extend existing Hono, itty-router, etc application, without touching old routes
- CLI to extract the schema.json from your code (npx chanfana) - see CLI Documentation

Getting started

Get started with a template with this command:

``bash
npm create cloudflare@latest -- --type openapi
`

Installation

`bash
npm i chanfana --save
`

Command-Line Interface (CLI)

Chanfana includes a CLI tool to help you extract the OpenAPI schema from your Cloudflare Worker project. This is useful for generating a static schema file, for example, in CI/CD pipelines.

The basic command is:
`bash
npx chanfana
`
This will start your worker using wrangler dev, fetch the schema from /openapi.json, and save it to schema.json.

For more details on options and usage, please refer to the CLI Documentation.

Minimal Hono Example

`ts
import { fromHono, OpenAPIRoute } from 'chanfana'
import { Hono } from 'hono'
import { z } from 'zod'

export type Env = {
// Example bindings
DB: D1Database
BUCKET: R2Bucket
}
export type AppContext = Context<{ Bindings: Env }>

export class GetPageNumber extends OpenAPIRoute {
schema = {
request: {
params: z.object({
id: z.string().min(2).max(10),
}),
query: z.object({
page: z.number().int().min(0).max(20),
}),
},
}

async handle(c: AppContext) {
const data = await this.getValidatedData()

return c.json({
id: data.params.id,
page: data.query.page,
})
}
}

// Start a Hono app
const app = new Hono<{ Bindings: Env }>()

// Setup OpenAPI registry
const openapi = fromHono(app)

// Register OpenAPI endpoints (this will also register the routes in Hono)
openapi.get('/entry/:id', GetPageNumber)

// Export the Hono app
export default app
``

Feedback and contributions

chanfana aims to be at the core of new APIs built using
Workers and define a pattern to allow everyone to
have an OpenAPI-compliant schema without worrying about implementation details or reinventing the wheel.

chanfana is considered stable and production ready and is being used with
the Radar 2.0 public API and many other Cloudflare products.

You can also talk to us in the Cloudflare Community or
the Radar Discord Channel