Skip to content

commandBackend and APIs

Document Endpoint

Writes reference docs for one endpoint from the real code: parameters, responses, errors and a working example call.

npx workspacetemplates add document-endpoint --tool claude-code

Writes 1 file to .claude/commands/

.claude/commands/document-endpoint.md14 lines · 1.1 KBFile
---
description: "Writes reference docs for one endpoint from the real code: parameters, responses, errors and a working example call."
argument-hint: "[method and path, or handler file]"
---

Write reference documentation for this endpoint: $ARGUMENTS

1. Locate the route, its handler, validation schema, auth middleware and tests. Read all of them.
2. Look for existing API docs (docs folder, README, OpenAPI file). Match their headings and tone. If none exist, use plain Markdown.
3. Document, in this order: purpose in one sentence, method and path, authentication and required roles, path and query parameters, request body fields (type, required, limits), success response with status and fields, every error status with its cause and body, rate limits if any.
4. Build a request example that really works (curl with a dummy token) and the matching real-shaped response. Take values from tests or fixtures, never invent fields the code does not return.
5. If the code, tests and any older doc disagree, do not choose silently. List each mismatch.

Show the finished page. Ask before saving it or overwriting an existing doc file.

What it does

API docs go stale when they are written from memory. This command reads the handler, its validation and its tests, then writes the reference from what the code actually does.

The result follows the format of your existing docs when there is one. If the code and the tests disagree, it lists the mismatch instead of picking a side quietly.

Example

you › /document-endpoint POST /invoices

agent › Documented POST /invoices: bearer auth, role billing, body fields customerId, items[], dueDate; 201 returns the invoice; errors 400, 401, 403, 422.
Mismatch: the old doc says dueDate is optional, but the schema requires it.
Save to docs/api/invoices.md?

Questions

Does it guess response fields?
No. Fields come from the handler code, serializers and test fixtures, and anything unclear is flagged as a question.
Can it update an OpenAPI file?
It writes the page in your docs format. For spec changes, the Update OpenAPI command is the better tool.
  • Add Caching

    CommandBackend and APIs

    Free
  • Add Endpoint

    CommandBackend and APIs

    Free
  • Add Health Check

    CommandBackend and APIs

    Free
  • Add Pagination

    CommandBackend and APIs

    Free