| name | api-documentation |
| description | OpenAPI 3.1 specification writing, request/response examples, error documentation, versioning, and interactive API portal patterns. |
API Documentation Principles
Guidelines for creating comprehensive, developer-friendly API documentation.
When to Invoke
- Writing or updating OpenAPI/Swagger specs
- Documenting API endpoints, schemas, and errors
- Creating SDK documentation and integration guides
- API versioning and migration documentation
OpenAPI Specification
Structure
openapi: 3.1.0
info:
title: Task API
version: 1.0.0
paths:
/api/v1/tasks:
post:
summary: Create a task
operationId: createTask
tags: [Tasks]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTaskRequest'
example:
title: "Deploy fix"
priority: "high"
responses:
'201':
description: Task created
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
Principles
- Every endpoint has
operationId โ used for SDK generation.
- Every endpoint has examples โ request and response.
- Reusable components โ
$ref for schemas, responses, parameters.
- Error responses documented โ every possible error code with description.
Error Documentation
Standard Error Format
{
"error": {
"code": "TASK_NOT_FOUND",
"message": "Task 'abc123' not found",
"details": [
{ "field": "id", "issue": "No task exists with this ID" }
]
}
}
Error Code Catalog
Document every error code with:
- Code โ machine-readable identifier
- HTTP Status โ corresponding status code
- Description โ what caused the error
- Resolution โ how to fix it
Versioning Documentation
- Changelog โ every API version change documented.
- Migration guides โ step-by-step upgrade instructions.
- Deprecation notices โ minimum 6 months warning.
- Breaking changes โ clearly marked with migration path.
Documentation Checklist
Related
- API Design Principles @.gemini/skills/api-design-principles/SKILL.md
- Documentation Principles GEMINI.md ยง Documentation Principles