update-api-docs_skill

Overview

This skill automates updating the API reference docs by pulling the latest OpenAPI spec from production and regenerating Docusaurus API pages. It ensures the local spec is replaced in the expected minified format and runs the docusaurus-plugin-openapi-docs generation steps. The outcome is a refreshed set of .api.mdx/.tag.mdx files and an updated sidebar for the docs site.

How this skill works

The skill downloads the production openapi.json into docs/docs/reference/openapi.json, preserving the server-provided minified format. It runs the plugin's clean and generate npm scripts (passing the OpenAPI config ID) to remove and recreate generated API pages and sidebar. Optionally, it can start the local dev server so you can preview the updated docs at /docs/reference/api.

When to use it

• After backend API changes that modify or add endpoints in production.
• Before releasing documentation updates tied to a new backend deployment.
• When the OpenAPI spec hosted in production has been corrected or extended.
• As part of a docs maintenance sweep to keep reference docs current.
• When automated doc generation fails and a manual refresh is required.

Best practices

• Always download the spec into docs/docs/reference/openapi.json and keep the minified format to avoid noisy diffs.
• Run npm install inside docs/ on first use to avoid docusaurus: not found errors.
• Pass the OpenAPI config ID (agenta) to clean and gen scripts: npm run clean-api-docs -- agenta.
• Preview changes locally with npm run start and verify /docs/reference/api before committing.
• Commit all generated files together (openapi.json, .api.mdx, .tag.mdx, sidebar.ts) with a single clear message.

Example use cases

• Update API reference after deploying a new endpoint that needs documentation.
• Regenerate docs when the production spec was fixed for an incorrect schema.
• Include the docs update as a step in a release checklist for coordinated backend and docs changes.
• Quickly troubleshoot and verify generated docs when CI/TG doc generation fails.
• Refresh API docs after merging an API contract change from the API team.