---
title: "Generate an API Reference"
description: "Generate API reference pages in Beacon from an OpenAPI 3 file, with parameters, responses, and code samples for each endpoint."
url: https://beacon-arodoni.vercel.app/openapi
---

# Generate an API Reference

If you have an OpenAPI file that describes your API, Beacon can build a reference page for each endpoint when you build the site. You don't need to write the pages or add them to the navigation.

## Add your OpenAPI file

Add your file to the `content/` folder with one of the following names:

- `content/openapi.yaml`

- `content/openapi.yml`

- `content/openapi.json`

Keep only one of these files, or the build fails. To remove the generated pages, delete the file.

The development server reads the file on each request, so refresh the page to see your changes. Restart the server to update the `.md` versions of the pages.

## Generated pages

An **API Reference** item appears in the top navigation. The sidebar groups endpoints by their first tag, in the order of the file's `tags` list, and shows each endpoint's HTTP method. Each endpoint gets a page at `/api-reference/` followed by a page name. The page name comes from the endpoint's `operationId`, or from its method and path if it doesn't have one.

Each page shows the following:

- The method, the path, and the first server URL.

- The summary as the page title, and the description as the introduction. Descriptions support Markdown.

- The authentication that the endpoint uses.

- Path, query, header, and cookie parameters.

- The request body and each response, including nested fields and an example.

- Code samples in cURL, JavaScript, and Python.

Generated pages also appear in site search, the sitemap, and `/llms.txt`, and each one has a Markdown version at its URL plus `.md`. Responses from the [REST API](https://beacon-arodoni.vercel.app/rest-api) don't include them.

## Add an introduction page

To show your own pages above the endpoints, such as an overview of authentication or a list of endpoints, add them to a navigation group titled `API Reference`.

1. **Create the page**

   Add a file to `content/docs/`, such as `content/docs/rest-api.mdx`.

2. **Add the navigation group**

   In `content/nav.config.ts`, add a group with the following title and your page as an item:

   ```ts
   {
     title: "API Reference",
     href: "/rest-api",
     items: [{ title: "REST API", href: "/rest-api" }],
   }
   ```

   The title must match exactly. The endpoints appear after your items, and the group's `href` sets the page that opens from the top navigation.

3. **Link to the endpoint pages**

   Optional: Link to an endpoint from your page with its page name. For example, an endpoint with the `operationId` value `listDocs` has a page at `/api-reference/list-docs`.

For an example of this layout, see the [REST API](https://beacon-arodoni.vercel.app/rest-api) page and its group in the navigation.

## Improve the generated examples

Beacon uses the `example` and `examples` values in your file. If a value has no example, the page uses the schema's `default` value or first `enum` value, or a placeholder for its type, such as `string` or `0`.

Code samples use placeholders such as `YOUR_TOKEN` for credentials and for any required path or query value without an example. To show realistic requests, add examples to your parameters and schemas.

## File requirements

Beacon fails the build with an error message if your file has any of the following problems:

- **Unsupported version:** The file must use OpenAPI 3.x. To use a Swagger 2.0 file, first convert it with a tool such as [swagger2openapi](https://www.npmjs.com/package/swagger2openapi).

- **External references:** Each `$ref` value must point to a location in the same file, such as `#/components/schemas/User`. If your file spans several files, bundle them first.

- **Broken references:** Each `$ref` value and each security scheme that an endpoint uses must exist in the file.

- **Duplicate page names:** Two endpoints can't produce the same page name. Give them different `operationId` values.

Beacon checks only for these problems and doesn't validate the whole file against the OpenAPI specification. To catch other mistakes, run a separate linter, such as [Spectral](https://github.com/stoplightio/spectral).

## Limitations

- Pages don't include a playground for sending live requests.

- Documentation variables don't apply inside the OpenAPI file.

- Code samples show the first security option for an endpoint that allows several.