Agent skill · writing content · aj-geddes
api-reference-documentation
Create comprehensive API reference documentation with OpenAPI/Swagger specs, REST endpoints, authentication, examples, and SDKs. Use when documenting REST APIs, GraphQL APIs, endpoint documentation, or OpenAPI specifications.
Why this skill is useful
Provides detailed guidelines and examples for creating OpenAPI specifications and API documentation that the AI wouldn't reliably generate on its own.
What it needs
About 1k tokens when loaded. Last updated 2026-03-04. 307 stars on the source repository.
What this skill does
API Reference Documentation Table of Contents Overview When to Use Quick Start Reference Guides Best Practices Overview Generate professional API documentation that developers can use to integrate with your API, including endpoint specifications, authentication, request/response examples, and interactive documentation. When to Use Documenting REST APIs Creating OpenAPI/Swagger specifications GraphQL API documentation SDK and client library docs API authentication guides Rate limiting documentation Webhook documentation API versioning guides Quick Start Minimal working example: Reference Guides Detailed implementations in the references/ directory: Guide Contents --- --- OpenAPI Specification Example openapi: 3.0.3 List Products List Products Best Practices ✅ DO Use OpenAPI 3.0+ specification Include request/response examples for every endpoint Document all query parameters and headers Provide authentication examples Include error response formats Document rate limits and pagination Use consistent naming conventions Include SDK examples in multiple languages Document webhook payloads Provide interactive API explorer (Swagger UI) Version your API documentation Include migration guides for breaking changes ❌ DON'T Skip error response documentation Forget to document authentication Use inconsistent terminology Leave endpoints undocumented Ignore deprecation notices Skip versioning information
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aj-geddes/api-reference-documentation