Announcing OpenAPI Support

by Fiberplane Team on Dec 5, 2024

Nowadays, building HTTP APIs for external use without delivering an OpenAPI spec is like shipping IKEA furniture without assembly instructions.

OpenAPI serves as an instruction manual for your API and is an open standard that can be interpreted by various tools to display information on how to interact with your API.

Today, we are excited to announce that Fiberplane has added automagical support for OpenAPI specs generated with Hono’s Zod OpenAPI extension, building an IKEA-grade catalog for your APIs directly into Fiberplane Studio!

OpenAPI Support in Fiberplane

Fiberplane’s initial support for OpenAPI specs integrates API documentation into Studio, providing a central place to test, debug, and verify your Hono APIs.

On one hand, the OpenAPI spec helps design the correct payload. On the other hand, it helps you verify if the schemas and routes are correctly defined with Zod and fine-tune your application’s API spec.

The Fiberplane client library now detects OpenAPI specs generated by OpenAPIHono apps, and Fiberplane Studio displays the corresponding docs.

When an OpenAPI definition is detected, a new tab in Studio will show a given route’s docs.

You can view the expected responses and reference the required input parameters along with their types, making it simple to craft test payloads for your API.

Leveraging Hono Zod

Let’s look at how to set this up. First, create your Hono app with OpenAPI support:

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

The application can then use Zod schemas to define request and response parameters and bodies:

import { z } from "@hono/zod-openapi";

// Schema that defines the body of a request to create a new user
const NewUserSchema = z
  .object({
    name: z.string().openapi({
      example: "John Doe",
      description: "The name of the user"
    }),
    age: z.number().openapi({
      example: 42,
      description: "The user's age"
    })
  })
  .openapi("NewUser");

Next, you can leverage Zod to define the routes of your API and use the schemas you’ve defined:

import { createRoute } from "@hono/zod-openapi";

// Define the request/response schema for a route to create a new user
const createUserRoute = createRoute({
  method: "post",
  path: "/users",
  title: "CreateUser",
  description: "Create a new user",
  request: {
    body: {
      content: {
        "application/json": {
          schema: NewUserSchema
        }
      }
    }
  },
  responses: {
    201: {
      content: {
        "application/json": {
          schema: UserSchema
        }
      },
      description: "Newly created user"
    }
  }
});

Use the route in your application:

app.openapi(createUserRoute, async (c) => {
  //your business logic
});

Generate OpenAPI docs from your application by adding:

// Mount the api documentation
// The OpenAPI documentation will be available at /doc
app.doc("/doc", {
  openapi: "3.0.0",
  info: {
    version: "1.0.0",
    title: "Simple Hono OpenAPI API"
  }
});

And that’s it! You’ve now added OpenAPI support to your Hono application. Your documentation will automatically update whenever you change your code, and Studio will leverage your spec to provide a better development experience. Try it out by visiting the /doc endpoint of your application!

---

That’s a wrap for today. Keep an eye out for our final Mega Launch Week release tomorrow.

🚀 Mega Launch Week Check out all the new features and updates from Fiberplane's mega launch week