API Documenter

Purpose

Provides expertise in creating clear, accurate, and developer-friendly API documentation. Specializes in OpenAPI 3.x specifications, GraphQL schema documentation, and interactive API references.

When to Use

• Writing OpenAPI/Swagger specifications

• Documenting REST API endpoints

• Creating GraphQL schema documentation

• Building interactive API references

• Writing API getting-started guides

• Documenting authentication flows

• Creating SDK usage examples

Quick Start

Invoke this skill when:

• Writing OpenAPI/Swagger specifications

• Documenting REST API endpoints

• Creating GraphQL schema documentation

• Building interactive API references

• Writing SDK usage examples

Do NOT invoke when:

• Designing API architecture (use api-designer)

• Writing user-facing product docs (use technical-writer)

• Creating internal system docs (use document-writer)

• Building the actual API (use backend developer skills)

Decision Framework

Documentation Type: ├── New API → OpenAPI spec first, then guides ├── Existing API → Audit endpoints, generate spec ├── GraphQL → Schema docs + query examples ├── SDK/Library → Code samples + quickstart └── Microservices → Service catalog + contracts

Core Workflows

1. OpenAPI Specification Creation

• Inventory all endpoints and methods

• Define request/response schemas

• Document parameters and headers

• Add authentication requirements

• Include example requests/responses

• Validate spec with linting tools

2. API Reference Documentation

• Group endpoints by resource or domain

• Write clear endpoint descriptions

• Document all parameters with types

• Provide request/response examples

• Include error codes and handling

• Add authentication examples

3. API Getting Started Guide

• Explain authentication setup

• Show first API call example

• Walk through common use cases

• Include SDK installation steps

• Provide troubleshooting tips

• Link to full reference docs

Best Practices

• Use consistent terminology across all docs

• Provide copy-pasteable code examples

• Include both success and error responses

• Version documentation with API versions

• Test all code examples before publishing

• Add rate limiting and quota information

Anti-Patterns

Anti-Pattern Problem Correct Approach

No examples Developers guess at usage Include request/response examples

Outdated docs Breaks developer trust Automate doc generation from code

Missing errors Surprise failures in production Document all error codes

Jargon-heavy Confuses new developers Use clear, simple language

No versioning Breaking changes unclear Version docs with API