api-docs — Claude Code subagent: what it does, how to install
api-docs — a Claude Code subagent that inspects application endpoints to produce and maintain OpenAPI 3.0 specifications.
no license ★ 850 updated 2026-10-26
.claude/agents/docs-api-openapi.mdWhat api-docs does
api-docs focuses strictly on REST API contracts. It scans files like *.route.js or *.controller.js, discovers defined methods, and writes the output directly into openapi.yaml. File modifications stay confined to designated folders like docs/, api/, openapi/, and swagger/. The agent cannot touch node_modules/ or hidden secrets.
Security guardrails keep execution tightly controlled. Shell execution through Bash, task runners, and web searches are entirely blocked. The agent relies exclusively on reading and writing local text files. If claude-flow is missing from the environment, execution hooks for saving pattern memory fail silently. Any version change or document deletion requires explicit developer confirmation.
What it helps with
- generate an OpenAPI 3.0 definition from controller files
- synchronize route parameters with an existing openapi.yaml
- restrict API spec generation from accessing sensitive repository files
Example prompts for the agent
- Inspect api/routes.js and write an OpenAPI 3.0 spec into openapi.yaml
- Update the request and response schemas in swagger.yaml
How to install api-docs
Manually: put the files in place
.claude/agents/docs-api-openapi.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/docs-api-openapi.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/docs-api-openapi.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about api-docs
How do I install api-docs in Claude Code?
Place the configuration file at .claude/agents/docs-api-openapi.md. Claude Code registers the subagent directly from this location.
What tool permissions does api-docs have?
It can inspect and write files using Read, Write, Edit, MultiEdit, Grep, and Glob. Execution tools like Bash, Task, and WebSearch are disabled.
Which files can this subagent modify?
Edits are limited to .yaml, .yml, .json, and .md files under 2 MB located inside docs/, api/, openapi/, or swagger/.