API Reference Documentation
Documentsapi-reference-documentationAPI Reference Documentation is an Agent Skill for documents published in the aj-geddes/useful-ai-prompts repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/aj-geddes/useful-ai-prompts/blob/HEAD/skills/api-reference-documentation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/api-reference-documentation, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
API Reference Documentation
Table of Contents
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:
openapi: 3.0.3
info:
title: E-Commerce API
description: |
Complete API for managing e-commerce operations including products,
orders, customers, and payments.
## Authentication
All endpoints require Bearer token authentication. Include your API key
in the Authorization header: `Authorization: Bearer YOUR_API_KEY`
## Rate Limiting
- 1000 requests per hour for authenticated users
- 100 requests per hour for unauthenticated requests
## Pagination
List endpoints return paginated results with `page` and `limit` parameters.
version: 2.0.0
contact:
name: API Support
email: [email protected]
url: https://example.com/support
license:
name: MIT
url: https://opensource.org/licenses/MIT
// ... (see reference guides for full implementation)
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