# Generate an API Reference From an OpenAPI Spec in a Starlight Site

Yes. An agent adds the starlight-openapi plugin to your Starlight docs, points it at your spec, adds the pages to the sidebar, builds the site and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-openapi-docs/starlight/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the site before it adds a plugin. In a site like the `examples/basics` starter in withastro/starlight, `package.json` depends on `@astrojs/starlight` 0.42.7, `astro` 7.2.10 and `sharp`, with `dev`, `build` and `preview` scripts and nothing else. `astro.config.mjs` configures `starlight()` with the title `My Docs`, one GitHub `social` link and a two-group `sidebar`: `Guides`, which lists `guides/example` by slug, and `Reference`, which autogenerates from the `reference` directory. `src/content.config.ts` defines the `docs` collection with `docsLoader()` and `docsSchema()`, and `src/content/docs/` holds three pages, a splash `index.mdx`, `guides/example.md` and `reference/example.md`. `tsconfig.json` extends `astro/tsconfigs/strict`. In the monorepo this starter lives in, the root `package.json` pins pnpm 12.11.2 and Node 24.18.0 through `devEngines`, and a `size-limit` entry keeps `examples/basics/dist/index.html` under 7 kB gzipped, so a change that adds weight to the home page would show up there.

Then it checks that the plugin fits the versions it found. `starlight-openapi` 0.27.0 declares peer dependencies on `@astrojs/starlight` at or above 0.41.0, `astro` at or above 7.0.2 and `@astrojs/markdown-satteri`, which this site satisfies, and it renders Swagger 2.0, OpenAPI 3.0 and 3.1 documents from a local path or a URL. The agent installs it with the package manager the lockfile belongs to, imports `starlightOpenAPI` and `openAPISidebarGroups` in `astro.config.mjs`, adds `plugins: [starlightOpenAPI([{ base: 'api', schema: '<your spec path>' }])]` to the Starlight options with a `label` for the sidebar group, and spreads `...openAPISidebarGroups` after the existing `Reference` group so the generated entries sit where a reader expects them. The `base` becomes the route prefix, so every operation renders under `/api/`, and the agent checks it does not collide with an existing content directory.

The spec is read, not assumed. The agent opens the OpenAPI document the prompt names, notes its version, its `servers`, its tags and how many operations it holds, and whether operations have `operationId` and summaries, because those become the page titles and sidebar labels. A spec with no tags produces one flat group, and the pull request says so. If the document lives in another repository, the plugin's remote `schema` URL is used instead of copying the file, and the pull request says that a build then depends on that URL answering.

It builds the site to prove the pages exist. `pnpm build` runs `astro build`; the agent reads the output for the generated routes, lists `dist/api/` to confirm one directory per tag and operation, opens one rendered page to check the request and response sections and the generated code snippets, and runs `astro check` for type errors in the config. The three existing pages and the splash page are left as they are, and `README.md` gains one paragraph on where the spec lives and how to regenerate the reference, which is simply to rebuild.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a generated API reference to this Starlight documentation site from the OpenAPI document at openapi/openapi.yaml in this repository. Read package.json, astro.config.mjs, src/content.config.ts and the pages under src/content/docs first, and read the OpenAPI document to note its version, tags and operation count. Install starlight-openapi with the package manager the lockfile belongs to, check its peer dependency ranges against the installed @astrojs/starlight and astro versions, and configure it in astro.config.mjs with base set to api, the schema path, and a sidebar label, spreading openAPISidebarGroups into the existing sidebar after the Reference group. Run the production build, confirm the generated pages under dist/api, open one rendered operation page, and run astro check. Add a short paragraph to README.md on where the spec lives. Do not change the existing content pages, and open a pull request that lists the generated routes and anything in the spec, such as missing tags or operationIds, that affects how the pages read.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `starlight-openapi` to `package.json` and the lockfile, changes `astro.config.mjs` to load the plugin and spread its sidebar groups, and adds a paragraph to `README.md`. The description lists the routes the build generated under `/api/`, one per tag and operation, states the OpenAPI version and operation count it read from the spec, and names anything in the spec that affects the output, such as operations without `operationId` that fall back to method and path as their title.

The run's record keeps the install output with the resolved plugin version, the full `astro build` log, the `dist/api/` listing, the rendered page it inspected and the `astro check` result, so a reviewer can see the site built with the plugin before the preview deployment runs.

Before merging, a reviewer opens the preview, reads two or three generated operation pages against the spec, and decides whether the group should be collapsed by default or renamed, both of which are one-line options on the plugin configuration.

## Run it on every docs site per service

A platform team with one Starlight site per service sends this body once per repository to `POST /o/{org}/sessions`, each with its own repository in `resources` and the path of that service's spec in `input`, with a `request_id` that is a UUID v5 of the repository's full name so a retried call returns the run already started rather than a second pull request. Each run reads its own `astro.config.mjs`, so a site that already has plugins gets the new one appended rather than a replaced array.

Once the plugin is in place, no further run is needed when the spec changes: the reference is regenerated by the site's own build. A `webhook_url` on the key reports each `run.completed` with the pull request in `result`, and a `run.failed` names a site whose build broke on the plugin, for instance one on a Starlight version below the plugin's peer range.

## Why run it on Rush?

The place this goes wrong is between the versions: a plugin whose peer range excludes the installed Starlight, a `base` that collides with a content directory, a spec without tags that renders as one long group. The agent installs, configures and builds in its own sandbox with the real spec and the real lockfile, so the first `astro build` with the plugin happens there and its log is kept, not on the reviewer's preview deployment.

The build output and the rendered page the agent inspected stay with the run, so the pull request can list the exact routes that now exist and what the spec was missing, and the reviewer's job is to read a few pages, not to reproduce the setup.

## Frequently asked questions

### Where does the OpenAPI file live?

Wherever your repository keeps it; the request names `openapi/openapi.yaml` as an example and the agent uses the path you give. The plugin also takes a URL, which the agent uses when the spec is published by another repository, and the pull request then notes that a build depends on that URL answering.

### Will it change my existing pages or sidebar order?

No. The three content pages stay as they are and the generated group is spread into the sidebar after the existing groups. Moving it or collapsing it by default is a one-line option on the plugin configuration that the pull request points out.

### Does it work with Swagger 2.0 or only OpenAPI 3?

The plugin renders Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1. The agent reads the `swagger` or `openapi` field at the top of your document and reports which one it found.

### How is the reference kept up to date?

The pages are generated at build time from the spec path or URL, so every build of the docs site reflects the current document. There is no generated Markdown to commit and nothing to regenerate by hand.

## More Starlight jobs

- [Add an RSS Feed to a Starlight Docs Site](https://getrush.ai/run/add-rss-feed/starlight/)
- [Add a Typo Check to Starlight Docs](https://getrush.ai/run/add-typo-check/starlight/)
- [Add Versioned Docs to a Starlight Site](https://getrush.ai/run/add-versioned-docs/starlight/)

## The same job on other stacks

- [Generate OpenAPI Docs from a tRPC Router](https://getrush.ai/run/add-openapi-docs/trpc/)
- [Add OpenAPI Docs to a Vapor API](https://getrush.ai/run/add-openapi-docs/vapor/)
- [Add OpenAPI Docs to an Actix Web API](https://getrush.ai/run/add-openapi-docs/actix/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
