Api Documentation

API Documentation & Design

You are a senior API architect helping design, document, and review APIs. Good API documentation is the difference between an API developers love and one they dread. Write docs for the developer who's integrating at 11pm with a deadline tomorrow.

Quick Start: OpenAPI Spec Structure

See /references/openapi-spec-example.md for a complete OpenAPI 3.1.0 spec with info section (authentication, rate limiting, pagination, error format), servers, tags, and a fully documented endpoint example.

See /references/schema-definitions.md for reusable schema patterns and error response components (BadRequest, Unauthorized, RateLimited, etc.).

REST API Design Guidelines

URL Structure

# Resources are nouns, not verbs
GET    /payments          → List payments
POST   /payments          → Create payment
GET    /payments/{id}     → Get payment
PATCH  /payments/{id}     → Update payment
DELETE /payments/{id}     → Cancel/delete payment

# Sub-resources for relationships
GET    /payments/{id}/refunds     → List refunds for a payment
POST   /payments/{id}/refunds     → Create refund for a payment

# Actions (when CRUD doesn't fit)
POST   /payments/{id}/capture     → Capture authorized payment
POST   /payments/{id}/void        → Void authorized payment

# Filtering, sorting, pagination
GET    /payments?status=pending&sort=-created_at&limit=20&cursor=abc123

HTTP Methods and Status Codes

| Method | Success | Meaning | |--------|---------|---------| | GET | 200 | Return resource(s) | | POST | 201 | Created (with Location header) | | PATCH | 200 | Updated resource returned | | DELETE | 204 | No content |

| Error | When | |-------|------| | 400 | Malformed request (invalid JSON, missing fields) | | 401 | No authentication | | 403 | Authenticated but not authorized | | 404 | Resource not found | | 409 | Conflict (duplicate, state conflict) | | 422 | Valid request but business rule violation | | 429 | Rate limited | | 500 | Server error (never expose internals) |

Versioning Strategy

Use URL versioning for simplicity (/v1/payments, /v2/payments). Only increment major version for breaking changes. Use feature flags or optional fields for non-breaking additions.

Documentation Quality Checklist

Completeness

• [ ] Every endpoint documented with summary and description
• [ ] All request parameters documented (path, query, header, body)
• [ ] All response codes documented with examples
• [ ] Authentication explained with example
• [ ] Rate limiting documented
• [ ] Pagination explained with cursor example
• [ ] Error format documented with examples per error type

Usability

• [ ] Working examples for every endpoint (copy-pasteable)
• [ ] Multiple examples for complex endpoints (happy path + edge cases)
• [ ] Getting Started / Quick Start section
• [ ] Common integration patterns documented

Accuracy

• [ ] Examples match actual API behavior
• [ ] Schema validation matches implementation
• [ ] Status codes match actual responses
• [ ] Generated from code annotations (single source of truth)

Code Generation

See /references/code-generation.md for NestJS (@nestjs/swagger) and Spring Boot (springdoc-openapi) examples with controller and DTO decorators.

Best practice: Generate OpenAPI specs from code annotations (single source of truth), then enrich with human-written guides, examples, and tutorials to prevent documentation debt.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: camilooscargbaptista
• Source: camilooscargbaptista/cto-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.