OpenAPI

Load an OpenAPI document from a local file, public asset, or URL and generate an API reference.

Add an OpenAPI document to generate an API reference from its operations. The official starters already load the Heyo Docs integration; you only need to add the schema to the documentation configuration.

Add a schema

Place the schema where its generated endpoint sections should appear in the sidebar. It accepts JSON or YAML and needs a top-level paths object.

heyo-docs.config.ts

export default heyoDocs({
  content: "content",
  groups: [
    {
      group: "API Reference",
      icon: "code",
      sections: [
        { schema: "./openapi.json" },
      ],
    },
  ],
});

The schema object contains only schema. Heyo Docs replaces it with endpoint sections grouped by OpenAPI tag. You can place regular MDX pages before or after it for an overview, authentication, or migration guide.

Choose the source

Source	Example	Use when
Local file	`"./openapi.json"` or `"./openapi.yaml"`	The schema lives under `content/`.
Public asset	`"/openapi.json"`	The file is served from the app's `public/` directory.
URL	`"https://api.example.com/openapi.json"`	The schema is publicly available during the build.

Remote schemas are fetched during development and each production build, so use a stable or pinned URL. Private URLs that require credentials are not supported; commit the schema or provide a public build artifact instead.

What is generated

Each API operation becomes a static reference page. Tags organize the sidebar; the operation method, path, parameters, request body, responses, and local schemas are displayed automatically. A schema change requires a new build and deployment.

If the document declares an API server, the generated templates can also show Try it. Requests run through the application's server and are limited to servers declared in the schema. Treat that as a convenience for a safe test API, not as a replacement for authentication or rate limiting.