API Documentation

When building or updating a REST API, ensure every endpoint is documented for consumers.

Core Rules

1. Document every endpoint — method, path, one-line summary, request body shape (with required fields marked), success response shape with status code, and error responses with status codes.

2. Use the framework's built-in docs when available:

   • FastAPI: add summary, response_description to decorators; add docstrings to handler functions; use Pydantic Field(description=...) on model fields. Docs auto-generate at /docs.
   • Express: use swagger-jsdoc with @openapi JSDoc annotations on route handlers + swagger-ui-express mounted at /api-docs.
   • Spring Boot: use springdoc-openapi with @Operation / @ApiResponse annotations.

3. When no framework tooling is available, write a markdown file (API.md or in README.md) covering every endpoint with the same elements listed in rule 1.

4. Always follow the task's output requirements exactly — if the task asks for a setup script, a verification script, a specific output file, or a specific docs URL path, implement those precisely. Do not skip or alter requested deliverables.

Common Mistakes to Avoid

WRONG — Documenting only the happy path:

POST /api/orders → 201 Created

RIGHT — Documenting success AND error responses:

POST /api/orders
  201: Order created  { "data": { "id": 42, ... } }
  400: Validation error  { "error": "items is required" }
  401: Unauthorized  { "error": "Missing auth token" }

WRONG — Listing fields without marking which are required:

Body: { customer_name, items, notes }

RIGHT — Clearly marking required vs optional:

Body:
  customer_name (string, required)
  items (array, required)
  notes (string, optional)

WRONG — FastAPI: omitting response_description, responses, and required/optional distinction:

@app.post("/items", status_code=201)
async def create_item(body: ItemCreate):
    ...

RIGHT — FastAPI: full decorator params, error responses declared, Pydantic model with clear required/optional:

class ItemCreate(BaseModel):
    name: str = Field(..., description="Item name")          # required (no default)
    quantity: int = Field(..., ge=1, description="Quantity")  # required
    notes: Optional[str] = Field(None, description="Notes")  # optional

@app.post("/items", status_code=201,
          summary="Create a new item",
          response_description="The newly created item",
          responses={400: {"description": "Validation error"}, 404: {"description": "Not found"}})
async def create_item(body: ItemCreate):
    """Create an item in the inventory."""
    ...

WRONG — Forgetting to document query parameters and path parameters:

GET /api/orders

RIGHT — Including all parameters:

GET /api/orders?status=active&page=1
  Path params: none
  Query params:
    status (string, optional) — filter by order status
    page (integer, optional, default: 1) — pagination

Checklist

• Every endpoint has: method, path, summary
• Request body shape documented with required fields marked
• Response shape documented for success and error cases
• Interactive docs accessible when framework supports it (Swagger UI, ReDoc, etc.)
• All task-specified output files and scripts are produced and functional

Verifiers

• api-docs-available — Provide API documentation for endpoint consumers