Get Started

Fiberplane is an embeddable, interactive playground for exploring and testing Hono APIs. It leverages OpenAPI to render rich API documentation and enable developers to send test requests through its UI.

1. Set up a Hono project

You can set up a basic Hono project via your terminal:

npm create hono@latest -- my-app

pnpm create hono@latest my-app

yarn create hono@latest my-app

If you want a project that includes a database, integration with Hono Zod OpenAPI, and is ready to deploy as a Cloudflare Worker, we recommend using HONC 🪿:

npm create honc-app@latest

pnpm create honc-app@latest

yarn create honc-app@latest

2. Add an OpenAPI spec to Hono

The Fiberplane Playground requires an OpenAPI spec to work. There are two packages that help you define an OpenAPI spec for your Hono application: Zod OpenAPI Hono helps you design an OpenAPI spec from the start, ensuring type safety between your code and the spec definitions. Hono OpenAPI generates a spec from your existing validation schemas, allowing for incremental adoption of OpenAPI for your api.

Zod OpenAPI Hono

Zod OpenAPI Hono provides input validation, type safety, and OpenAPI documentation. It extends the Hono class, and requires that you pass a specification of your routes before defining the logic of your handlers. This makes it possible to type-check your api inputs and outputs against your api spec.

Install the package alongside Hono and Zod:

npm i hono zod @hono/zod-openapi

pnpm add hono zod @hono/zod-openapi

yarn add hono zod @hono/zod-openapi

Create an app using Hono Zod

import { OpenAPIHono } from "@hono/zod-openapi";
const app = new OpenAPIHono<{
  Bindings: Bindings;
  Variables: Variables;
}>();

Define your input data schemas in Zod:

const UserResponseSchema = z
  .object({
    id: z.number().int().openapi({
      description: "The unique identifier for the user",
      example: 1
    }),

    name: z.string().min(1).max(255).openapi({
      description: "The user's full name",
      example: "Matthew"
    }),

    email: z.string().email().openapi({
      description: "The user's email address",
      example: "matthew@cloudflare.com"
    })
  })
  .openapi("User", {
    description: "Schema for user response including ID"
  });

const CreateUserSchema = UserResponseSchema.omit({ id: true }).openapi(
  "CreateUser",
  {
    description: "Schema for creating a new user"
  }
);

Define your routes in Zod and include the input and output data schemas if needed:

const createUser = createRoute({
  method: "post",
  path: "/api/user",
  request: {
    // Validate request body using Zod schemas
    body: {
      // NOTE: this is important to set to true, otherwise the route will accept empty bodies and invalid content types
      required: true,
      content: {
        "application/json": {
          schema: CreateUserSchema
        }
      }
    }
  },
  responses: {
    201: {
      content: {
        "application/json": {
          schema: UserResponseSchema
        }
      },
      description: "User created successfully"
    }
  }
});

Set up the application with the defined routes and define the application logic in the handlers:

app.openapi(createUser, async (c) => {
  const { name, email } = c.req.valid("json");
  // define the logic of the route handler

  return c.json(newUser, 201);
});

Make the OpenAPI spec available:

app.doc("/openapi.json", {
  openapi: "3.0.0",
  info: {
    title: "D1 Honc! 🪿☁️",
    version: "1.0.0",
    description: "D1 Honc! 🪿☁️"
  }
});

Hono OpenAPI

Hono OpenAPI allows for adding descriptions to the routes. Additionally, it supports multiple validation schemas. If your application already defines validation schemas, those can be reused easily to define an OpenAPI spec.

npm i hono-openapi @hono/zod-validator zod zod-openapi

pnpm add hono-openapi @hono/zod-validator zod zod-openapi

yarn add hono-openapi @hono/zod-validator zod zod-openapi

Define an input data schema with Zod and use the extended package to support openapi.

import { z } from "zod";
import "zod-openapi/extend";
const UserResponseSchema = z
  .object({
    id: z.number().int().openapi({
      description: "The unique identifier for the user",
      example: 1
    }),

    name: z.string().min(1).max(255).openapi({
      description: "The user's full name",
      example: "Matthew"
    }),

    email: z.string().email().openapi({
      description: "The user's email address",
      example: "matthew@cloudflare.com"
    })
  })
  .openapi({
    ref: "User",
    description: "Schema for user response including ID"
  });

const CreateUserSchema = UserResponseSchema.omit({ id: true }).openapi({
  ref: "CreateUser",
  description: "Schema for creating a new user"
});

Next add a description to the route:

import { describeRoute } from "hono-openapi";
import { resolver, validator as zValidator } from "hono-openapi/zod";

app.post(
  "/api/user",
  describeRoute({
    description: "Create a new user",
    requestBody: {
      content: {
        "application/json": {
          schema: resolver(CreateUserSchema)
        }
      }
    },
    responses: {
      201: {
        description: "The created user",
        content: {
          "application/json": {
            schema: resolver(UserResponseSchema)
          }
        }
      }
    }
  }),
  // Middleware to validate incoming request bodies
  zValidator("json", CreateUserSchema),
  async (c) => {
    const { name, email } = c.req.valid("json");

    // define what the route handler does

    return c.json(newUser);
  }
);

Make the OpenAPI spec available:

import { openAPISpecs } from "hono-openapi";
app.get(
  "/openapi",
  openAPISpecs(app, {
    documentation: {
      info: {
        title: "Hono",
        version: "1.0.0",
        description: "API for users"
      }
    },
    servers: [
      {
        url: "http://localhost:8787",
        description: "Local server"
      }
    ]
  })
);

Fiberplane’s createOpenAPISpec helper function

The other option is to integrate OpenAPI documentation into an existing Hono codebase. Refactoring the application to use Hono Zod OpenAPI or Rhinobase provides fine-grained documentation, offering long-term benefits, but requires more effort. For a quicker solution, Fiberplane provides a helper function to generate an OpenAPI spec from the existing code.

npm i @fiberplane/hono

pnpm add @fiberplane/hono

yarn add @fiberplane/hono

This step involves importing the createOpenAPISpec function from Fiberplane and creating an endpoint at /openapi.json to generate and return an OpenAPI spec.

import { createOpenAPISpec } from "@fiberplane/hono";

app.get("/openapi.json", (c) => {
  const spec = createOpenAPISpec(app, {
    info: { title: "My API", version: "1.0.0" }
  });
  return c.json(spec);
});

3. Add Fiberplane Middleware

Now that the OpenAPI spec is available, mount the Fiberplane middleware and point it to the OpenAPI spec.

npm i @fiberplane/hono

pnpm add @fiberplane/hono

yarn add @fiberplane/hono

import { createFiberplane } from "@fiberplane/hono";

app.use(
  "/fp/*",
  createFiberplane({
    openapi: {
      url: "/openapi.json"
    }
  })
);

After starting the application, Fiberplane’s native UI will be available at the /fp endpoint of the Hono application. For example, if the Hono app is running on http://localhost:8787, the Fiberplane Playground will be accessible at http://localhost:8787/fp/.

Next steps

Learn more about Fiberplane Playground Explore the features of the native built-in UI.