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
Get started with a template with this command:
npm create cloudflare@latest -- --type openapinpm i chanfana --saveChanfana 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:
npx chanfanaThis 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.
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<typeof this.schema>()
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 appchanfana 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