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
• Query, Path, Headers and Body typescript inference
• Fully written in typescript
• Class-based endpoints
• Extend existing Hono, itty-router, etc application, without touching old routes

Getting started

Get started with a template with this command:

1npm create cloudflare@latest -- --type openapi

Installation

1npm i chanfana --save

Minimal Hono Example

1import { fromHono, OpenAPIRoute } from 'chanfana'
2import { Hono } from 'hono'
3import { z } from 'zod'
4
5export type Env = {
6    DB: D1Database
7    BUCKET: R2Bucket
8}
9export type AppContext = Context<{ Bindings: Env }>
10
11export class GetPageNumber extends OpenAPIRoute {
12  schema = {
13    request: {
14      params: z.object({
15        id: z.string().min(2).max(10),
16      }),
17      query: z.object({
18        page: z.number().int().min(0).max(20),
19      }),
20    },
21  }
22
23  async handle(c: AppContext) {
24    const data = await this.getValidatedData<typeof this.schema>()
25
26    return c.json({
27      id: data.params.id,
28      page: data.query.page,
29    })
30  }
31}
32
33// Start a Hono app
34const app = new Hono()
35
36// Setup OpenAPI registry
37const openapi = fromHono(app)
38
39// Register OpenAPI endpoints
40openapi.get('/entry/:id', GetPageNumber)
41
42// Export the Hono app
43export 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