SKILL.md
API Reference Documentation
Table of Contents
- [Overview](#overview)
- [When to Use](#when-to-use)
- [Quick Start](#quick-start)
- [Reference Guides](#reference-guides)
- [Best Practices](#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:
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: api@example.com
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