← All Posts

How to Do API Documentation on Claude Code

Claude Code can generate, write, and maintain API documentation directly from your codebase using natural language prompts, slash commands, and persistent context files. It works best for developers who want to document REST endpoints, SDKs, or internal libraries without leaving the terminal. The main trade-off: documentation quality depends on how much context you give Claude, and long sessions can consume your usage limit quickly.

  • Claude Code reads source files and generates README, OpenAPI specs, and inline docs in a single session
  • The /context and CLAUDE.md file let you persist project-specific documentation conventions across sessions
  • Heavy documentation runs (scanning entire codebases) are token-intensive and can push you toward your 5-hour usage window limit

What is API documentation generation in Claude Code?

Claude Code is Anthropic's agentic CLI tool that gives Claude direct access to your local files, terminal, and shell environment. For API documentation, this means Claude can read your actual source code (controllers, route files, type definitions) and generate structured documentation output without you having to manually describe every endpoint.

Unlike pasting code into a chat window, Claude Code maintains a working directory context. It can traverse your project structure, read multiple files at once, and produce documentation that accurately reflects your real implementation, not a hypothetical one.

How to set up your project for API documentation

Before asking Claude to document anything, give it the right anchors. This reduces hallucinations and keeps the output consistent with your existing style.

1. Create or update your CLAUDE.md file

Claude Code automatically reads a CLAUDE.md file at the root of your project as persistent context. Use it to specify your documentation format (OpenAPI 3.1, JSDoc, Markdown, etc.), your preferred output file paths, and any conventions like required fields or response schema patterns. According to Anthropic's Claude Code docs, this file is the primary way to give Claude durable project-level instructions.

Example CLAUDE.md snippet:

## Documentation
- API docs go in /docs/api/
- Use OpenAPI 3.1 YAML format
- Every endpoint must include: summary, parameters, requestBody, responses
- Error responses follow RFC 7807 (application/problem+json)

2. Point Claude at your route files

Start a Claude Code session in your project root and give it a specific entry point. Vague prompts produce vague documentation. Be direct:

Document all endpoints in src/routes/. Generate an OpenAPI 3.1 YAML spec at docs/api/openapi.yaml.

Claude will read the route files, infer request/response shapes from your controllers and type definitions, and write the spec file. You can then iterate: "Add authentication details using Bearer tokens" or "Include example responses for every 200 status."

Useful slash commands for documentation workflows

Claude Code's slash commands are shortcuts that change how Claude interprets your next request. Several are particularly useful when doing documentation work:

  • /clear - Resets the conversation context. Use this between major documentation tasks (e.g., after finishing endpoint docs, before starting SDK docs) to avoid context bleed and reduce token usage.
  • /usage - Shows your current Claude Code usage. Essential for long documentation runs so you don't hit your limit mid-session while generating a large OpenAPI spec.
  • /compact - Summarizes the current context to free up context window space. Useful when documenting large codebases where Claude needs to hold many files in memory.
  • /memory - Lets you inspect or update the persistent memory Claude uses across sessions, separate from CLAUDE.md.

Step-by-step workflow for documenting a REST API

Here is a practical sequence that works well for most backend projects:

  1. Define conventions in CLAUDE.md - Output format, file paths, required fields, example style.
  2. Open Claude Code in your project root - Run claude from the terminal.
  3. Give a scoped, explicit prompt - Target a specific directory or file set, not "document everything."
  4. Review and iterate inline - Ask Claude to refine descriptions, add missing parameters, or adjust response schemas.
  5. Use /usage to monitor consumption - Documentation tasks can be surprisingly token-heavy when scanning many files.
  6. Commit the generated files - Claude Code can also run git add and git commit on your behalf if you ask it to.

For SDK documentation (TypeScript interfaces, Python classes), the same pattern applies: point Claude at your type files, specify the output format (TSDoc, Sphinx, or plain Markdown), and let it generate. Iterate with follow-up prompts to fill gaps.

How to document an API with existing tests

If you have API tests already written, they are excellent documentation source material. Claude can read your test files and extract real request/response examples, then embed them into your OpenAPI spec as examples objects:

Read our test suite in tests/api/ and generate example request/response pairs for every endpoint. Add them to docs/api/openapi.yaml under the examples field.

This produces documentation that is guaranteed to reflect actual behavior, not guessed shapes.

Managing usage limits during long documentation sessions

API documentation is one of those tasks where you load a lot of context upfront (route files, type definitions, existing docs) and then iterate through dozens of endpoints. That pattern burns through tokens faster than typical coding tasks.

Claude Code usage runs in rolling 5-hour windows. If you hit your limit mid-session, while Claude is halfway through generating a 50-endpoint OpenAPI spec, you face a hard stop. The output so far is saved to disk, but you lose your in-session context and have to re-explain conventions and progress when the window resets.

The practical fix is to know your usage level before you start a heavy documentation run, not after. Usagebar lives in your macOS menu bar and shows your Claude Code usage in real time, with alerts at 50%, 75%, and 90% of your limit. You can see at a glance whether you have enough headroom to tackle documenting a large module, or whether you should wait for your window to reset first. Credentials are stored in macOS Keychain. Pricing is pay-what-you-want, with a free option for students.

You can also check your current usage directly in Claude Code with the /usage command, or by visiting claude.ai/settings/usage.

Tips for higher-quality generated documentation

  • Scope tightly - "Document the /auth endpoints in src/routes/auth.ts" produces better output than "document the whole API."
  • Provide an example - Paste one well-written endpoint doc into your prompt as a style reference. Claude will match it.
  • Iterate, don't regenerate - Ask Claude to refine specific sections rather than rewriting the entire spec. This saves tokens and keeps good sections intact.
  • Use /compact before large scans - If Claude has been working for a while, compact the context before asking it to scan a new directory.
  • Let Claude write the changelog too - Once docs are generated, ask Claude to diff against the previous version and write a changelog entry.

Key takeaways

  1. Set documentation conventions in CLAUDE.md before starting, so Claude produces consistent output across sessions.
  2. Target specific files or directories in your prompts, not entire codebases at once.
  3. Use your existing test suite as a source for real request/response examples.
  4. Monitor your usage with /usage or Usagebar before starting heavy documentation runs.
  5. Use /compact to free context window space and /clear between unrelated documentation tasks.

Related guides

Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar