Learn-skills.dev update-api-docs

Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/agenta-ai/agenta/update-api-docs" ~/.claude/skills/neversight-learn-skills-dev-update-api-docs && rm -rf "$T"

manifest: data/skills-md/agenta-ai/agenta/update-api-docs/SKILL.md

source content

Update API Documentation

This skill guides you through updating the API reference documentation from the production OpenAPI specification.

Overview

The API documentation is generated from an OpenAPI spec using

docusaurus-plugin-openapi-docs

. The workflow involves:

Downloading the latest
```
openapi.json
```
from production
Replacing the local spec file
Regenerating the API documentation pages

File Locations

Purpose	Path
OpenAPI spec (source)	`docs/docs/reference/openapi.json`
Generated API docs	`docs/docs/reference/api/*.api.mdx`
Generated sidebar	`docs/docs/reference/api/sidebar.ts`
Docusaurus config	`docs/docusaurus.config.ts`

Steps

1. Download the OpenAPI spec from production

curl -s "https://cloud.agenta.ai/api/openapi.json" -o docs/docs/reference/openapi.json

Important: The file should be saved in minified format (single line, no pretty-printing) to match the existing format in the repository. The curl command above preserves the original format from the server.

2. Install dependencies (if needed)

If this is a fresh clone or dependencies haven't been installed:

cd docs
npm install

3. Clean existing generated API docs

cd docs
npm run clean-api-docs -- agenta

The

agenta

argument refers to the OpenAPI config ID defined in

docusaurus.config.ts

4. Regenerate API docs

cd docs
npm run gen-api-docs -- agenta

This will generate:

Individual
```
.api.mdx
```
files for each endpoint
```
.tag.mdx
```
files for API categories
```
sidebar.ts
```
for navigation

5. Verify the changes

Optionally, start the dev server to preview:

cd docs
npm run start

Then visit

http://localhost:5000/docs/reference/api

to verify the API docs render correctly.

Commit Guidelines

When committing these changes:

First commit - API docs update:

docs(api): update OpenAPI spec from production

Include all changed files:

```
docs/docs/reference/openapi.json
```
```
docs/docs/reference/api/*.api.mdx
```
```
docs/docs/reference/api/*.tag.mdx
```
```
docs/docs/reference/api/sidebar.ts
```

Troubleshooting

"missing required argument 'id'" error

The clean and generate commands require the config ID. Use:

npm run clean-api-docs -- agenta
npm run gen-api-docs -- agenta

"docusaurus: not found" error

Run

npm install

in the

docs/

directory first.

Deprecation warning about onBrokenMarkdownLinks

This is a known warning and can be safely ignored. It will be addressed in a future Docusaurus v4 migration.

Related Configuration

The OpenAPI plugin is configured in

docs/docusaurus.config.ts

[
  "docusaurus-plugin-openapi-docs",
  {
    id: "openapi",
    docsPluginId: "classic",
    config: {
      agenta: {
        specPath: "docs/reference/openapi.json",
        outputDir: "docs/reference/api",
        downloadUrl: "https://raw.githubusercontent.com/Agenta-AI/agenta/refs/heads/main/docs/docs/reference/openapi.json",
        sidebarOptions: {
          groupPathsBy: "tag",
          categoryLinkSource: "tag",
        },
      },
    },
  },
],