home / skills / secondsky / claude-skills / api-reference-documentation
/plugins/api-reference-documentation/skills/api-reference-documentation
This skill generates professional API reference documentation from OpenAPI specs, including endpoints, authentication, examples, and interactive exploration
npx playbooks add skill secondsky/claude-skills --skill api-reference-documentationReview the files below or copy the command above to add this skill to your agents.
---
name: api-reference-documentation
description: Creates professional API documentation using OpenAPI specifications with endpoints, authentication, and interactive examples. Use when documenting REST APIs, creating SDK references, or building developer portals.
---
# API Reference Documentation
Create comprehensive API documentation for developer integration.
## OpenAPI 3.0 Specification
```yaml
openapi: 3.0.3
info:
title: E-Commerce API
version: 1.0.0
description: API for managing products and orders
contact:
email: [email protected]
servers:
- url: https://api.example.com/v1
description: Production
- url: https://staging-api.example.com/v1
description: Staging
security:
- bearerAuth: []
paths:
/products:
get:
summary: List products
tags: [Products]
parameters:
- name: limit
in: query
schema: { type: integer, default: 20 }
- name: category
in: query
schema: { type: string }
responses:
'200':
description: Product list
content:
application/json:
schema:
$ref: '#/components/schemas/ProductList'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
Product:
type: object
required: [id, name, price]
properties:
id: { type: string, format: uuid }
name: { type: string, maxLength: 200 }
price: { type: number, minimum: 0 }
description: { type: string }
```
## Documentation Checklist
- [ ] All endpoints documented with examples
- [ ] Authentication methods explained
- [ ] Error responses specified
- [ ] Rate limits documented
- [ ] Pagination explained
- [ ] Webhooks documented (if applicable)
- [ ] SDK examples in multiple languages
## Best Practices
- Use OpenAPI 3.0+ specification
- Include request/response examples
- Document all parameters and headers
- Provide authentication examples
- Enable interactive API exploration
- Maintain version documentation
- Include migration guides for breaking changes
## Tools
- Swagger Editor / Swagger UI
- Redoc
- Postman Documentation
- Stoplight
This skill generates professional API reference documentation from OpenAPI specifications, including endpoints, authentication, schemas, and interactive examples. It streamlines developer onboarding by producing clear endpoint docs, code samples, and ready-to-use interactive API explorers. Use it to build SDK references, developer portals, or product integration guides.
Provide an OpenAPI 3.x spec or a collection of endpoints and authentication details. The skill parses paths, parameters, request/response schemas, and security schemes to produce organized docs with examples, code snippets, and interactive try-it features. It can output documentation compatible with Swagger UI, Redoc, or Postman and includes checklists for completeness and versioning.
What input formats does this skill accept?
It accepts OpenAPI 3.x specifications in YAML or JSON and can ingest endpoint lists with schema details.
Can it include interactive examples and try-it features?
Yes. Outputs are compatible with Swagger UI, Redoc, and Postman to enable interactive exploration and example execution.