Authoring API Docs Action

Produces precise, exhaustive API reference documentation — the information-oriented quadrant of the Diátaxis framework.

Load authoring-technical-docs first for the multi-pass workflow, style rules, and quality framework. This action provides the templates and API-specific rules.

Templates

Templates are located in the assets/ folder alongside this skill:

• assets/rest-endpoint-template.md — Use for documenting individual REST API endpoints. Covers authentication, path/query/body parameters, request and response examples, error codes, and rate limits.

• assets/sdk-function-template.md — Use for documenting SDK or library functions. Covers parameters, options, return values, errors, and a usage example.

Copy the relevant template and fill in all placeholder fields before publishing.

API-specific rules

• Every parameter must have a type. No exceptions. Complex types link to schema definitions.

• Every endpoint must have a working example. Copy-pasteable with clearly marked placeholders (YOUR_API_KEY ).

• Document all error codes. Include the code string, description, and resolution.

• Show both request and response. Always pair them.

• Use consistent field naming. Match the API's convention exactly — never translate.

• Document authentication once at the top, then reference from individual endpoints.

• Include rate limit information for every rate-limited endpoint.

• Version your docs if the API has versions.

Generating from OpenAPI specs

When an OpenAPI/Swagger spec is the input:

• Parse all paths, methods, parameters, and schemas

• Group endpoints by tag or resource

• Populate the endpoint template for each

• Create a "Data types" section for schemas referenced by $ref

• Use description fields as starting points — rewrite for clarity

• Use example fields in code examples

• Document security section as auth requirements at the top

Save output to docs/api/ .