All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading