write-endpoints

Documentation: chanfana.pages.dev

Source Code: github.com/cloudflare/chanfana

Overview

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
• Zod v4 compatible with full TypeScript inference
• 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

AI Skills

Chanfana provides AI coding assistant skills to help you build OpenAPI endpoints faster. Install them using npx skills:

npx skills install cloudflare/chanfana

Available skills:

• write-endpoints - Comprehensive guide for building OpenAPI endpoints with schema definition, request validation, CRUD operations, and D1 integration

Getting started

Or scaffold it locally with the create-cloudflare CLI:

npm create cloudflare@latest -- --template https://github.com/cloudflare/chanfana/tree/main/template

The template includes a complete Task API with Hono, D1, and Zod v4 — full CRUD endpoints, a custom endpoint example, integration tests, and auto-generated docs at /api/docs.

See template/README.md for full setup instructions.

Installation

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:

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

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 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