# api-docs

api-docs — a Claude Code subagent that inspects application endpoints to produce and maintain OpenAPI 3.0 specifications.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 850 repo stars
- Author: Claude Code
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ruvnet/agentic-flow/tree/HEAD/agentic-flow/.claude/agents/documentation/docs-api-openapi.md
- Updated: 2026-10-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/api-docs

## What it 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.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/docs-api-openapi.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/docs-api-openapi.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/docs-api-openapi.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ruvnet/agentic-flow/tree/HEAD/agentic-flow/.claude/agents/documentation/docs-api-openapi.md

## When to use it
- 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
- Inspect api/routes.js and write an OpenAPI 3.0 spec into openapi.yaml
- Update the request and response schemas in swagger.yaml

## Similar
- [api-docs-generator](https://affpapa.org/en/nevibecode/skills/api-docs-generator.md) — skill · 411 installs
- [adding-api-docs](https://affpapa.org/en/nevibecode/skills/adding-api-docs.md) — skill · 455 installs
- [generate-swagger-docs](https://affpapa.org/en/nevibecode/skills/generate-swagger-docs.md) — skill · 260 installs
- [generate-api-documentation](https://affpapa.org/en/nevibecode/commands/generate-api-documentation.md) — command · 1849 installs
- [api-documenter](https://affpapa.org/en/nevibecode/skills/api-documenter.md) — skill · 727 installs
- [api-reference-documentation](https://affpapa.org/en/nevibecode/skills/secondsky-api-reference-documentation.md) — skill · 472 installs

From the same set: [ruvnet/agentic-flow](https://affpapa.org/en/nevibecode/by/ruvnet/agentic-flow.md) — 76 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
