chanfana

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:

npm create cloudflare@latest -- --type openapi

Installation

npm i chanfana --save

Minimal Hono Example

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

export type Env = {
    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()

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

// Register OpenAPI endpoints
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