Skill: api-documentation

What I do

I guide the creation of clear, developer-centric API documentation. I focus on technical accuracy, intuitive structure, and practical examples to ensure developers can integrate with services quickly and reliably.

When to use me

• Writing OpenAPI (Swagger) or GraphQL schema documentation
• Creating developer portals, SDK guides, or integration tutorials
• Documenting authentication flows, error codes, and rate limits
• Writing API changelogs and migration guides for breaking changes

Core principles

1. Technical Accuracy — Every parameter, type, and endpoint must match the actual implementation exactly.
2. Context Before Mechanics — Explain what an endpoint achieves and why to use it before detailing its parameters.
3. Consistency — Use the same terminology, formatting, and data structures across all documented endpoints.
4. Clarity Through Examples — Provide realistic request and response samples for every endpoint.
5. Standardised Errors — Document every possible error code and the specific conditions that trigger them.

Patterns & examples

Endpoint Documentation Template

Every endpoint should follow a consistent structure:

• Summary: Concise one-line description of the action.
• Description: Detailed context, requirements, and side effects.
• Authentication: Required scopes, tokens, or headers.
• Parameters: Detailed table with types, constraints, and descriptions.
• Request Body: JSON example with realistic data.
• Responses: Success and error codes with examples.

Example Request/Response

POST /v1/users/register
Content-Type: application/json

{
  "email": "[email protected]",
  "full_name": "Dev User"
}

Anti-patterns to avoid

• ❌ Auto-generated fluff — Relying purely on tools without adding descriptive context and use cases.
• ❌ Missing error states — Documenting only the 200 OK response and leaving failures to guesswork.
• ❌ Stale examples — Using field names or data structures that have been deprecated or removed.
• ❌ Internal jargon — Using terms that only internal developers understand without explanation.

KB Reference

~/vaults/baphled/3. Resources/Knowledge Base/AI Development System/Skills/Communication-Writing/API Documentation.md

Related skills

• api-design — Align documentation with API design best practices.
• documentation-writing — Apply general technical writing standards.
• writing-style — Maintain a professional and consistent voice.
• release-notes — Document API changes and updates for consumers.