| name | api-documentation |
| description | Use when creating API documentation, implementing OpenAPI specifications, writing Swagger documentation, creating GraphQL schemas, and generating SDKs. Includes documentation best practices, API versioning, and API documentation automation. Based on CPTD and OpenAPI Specification certifications. |
| license | MIT |
API Documentation Skill — API Specialist
Overview
This skill provides comprehensive guidance for creating comprehensive API documentation. It covers OpenAPI specifications, Swagger documentation, GraphQL schemas, SDK generation, and API documentation best practices following CPTD and OpenAPI Specification certifications.
When to Use
Use this skill when:
- Creating API documentation
- Implementing OpenAPI specifications
- Writing Swagger documentation
- Creating GraphQL schemas
- Generating SDKs from API specs
- Documenting RESTful APIs
- Documenting GraphQL APIs
- Creating API documentation sites
- Implementing API versioning documentation
- Creating API examples
- Writing API tutorials
- Documenting API authentication
- Documenting API error handling
- Creating API changelogs
- Implementing API documentation automation
- Creating API documentation templates
- Documenting API best practices
- Creating API documentation style guides
- Implementing API documentation testing
- Creating API documentation metrics
- Documenting API security requirements
- Creating API documentation for developers
- Implementing API documentation updates
Do NOT use this skill when:
- Writing application business logic (use domain-driven skill)
- Designing database schemas (use database-design skill)
- Writing API endpoint specifications (use api-design skill)
- Performing security audits (use security-auditor skill)
- Writing SQL queries (use sql-best-practices skill)
- Designing multi-page website layouts (use design-system skill)
- Analyzing deployment configurations (use deployment skill)
- Writing documentation (use documentation-best-practices skill)
OpenAPI Specification
OpenAPI Structure
openapi: 3.1.0
info:
title: API Title
description: API description
version: 1.0.0
contact:
name: API Support
email: support@example.com
url: https://example.com/support
servers:
- url: https://api.example.com/v1
description: Production server
- url: https://staging-api.example.com/v1
description: Staging server
paths:
/users:
get:
summary: List all users
operationId: listUsers
tags:
- users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary: Create a new user
operationId: createUser
tags:
- users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Bad request
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
email:
type: string
format: email
UserList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- BearerAuth: []
OpenAPI Best Practices
┌─────────────────────────────────────────────────────────────┐
│ OpenAPI Best Practices │
├─────────────────────────────────────────────────────────────┤
│ Naming: │
│ - Use nouns for resource names │
│ - Use plural for collections │
│ - Use camelCase for properties │
│ - Use PascalCase for schemas │
│ │
│ Versioning: │
│ - Include version in URL path │
│ - Use Accept header for version │
│ - Document version changes │
│ │
│ Authentication: │
│ - Document all authentication methods │
│ - Provide authentication examples │
│ - Document token lifecycle │
│ │
│ Error Handling: │
│ - Document all error responses │
│ - Provide error codes and messages │
│ - Include error examples │
│ │
│ Pagination: │
│ - Document pagination parameters │
│ - Include pagination metadata │
│ - Provide pagination examples │
│ │
│ Filtering and Sorting: │
│ - Document filtering parameters │
│ - Document sorting parameters │
│ - Provide filtering examples │
└─────────────────────────────────────────────────────────────┘
GraphQL Schema Documentation
GraphQL Schema Structure
type Query {
user(id: ID!): User
users(limit: Int, offset: Int): UserConnection
me: User
}
type Mutation {
createUser(input: CreateUserInput!): User!
updateUser(id: ID!, input: UpdateUserInput!): User
deleteUser(id: ID!): Boolean!
}
type User {
id: ID!
name: String!
email: String!
createdAt: DateTime!
updatedAt: DateTime!
}
input CreateUserInput {
name: String!
email: String!
password: String!
}
input UpdateUserInput {
name: String
email: String
password: String
}
type UserConnection {
nodes: [User!]!
pageInfo: PageInfo!
totalCount: Int!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
scalar DateTime
GraphQL Best Practices
┌─────────────────────────────────────────────────────────────┐
│ GraphQL Best Practices │
├─────────────────────────────────────────────────────────────┤
│ Naming: │
│ - Use camelCase for field names │
│ - Use PascalCase for types │
│ - Use verbs for mutations │
│ │
│ Pagination: │
│ - Use cursor-based pagination │
│ - Implement Relay connection pattern │
│ - Document pagination fields │
│ │
│ Authentication: │
│ - Document authentication requirements │
│ - Document authorization requirements │
│ - Document token requirements │
│ │
│ Error Handling: │
│ - Document error types │
│ - Document error codes │
│ - Document error examples │
│ │
│ Input Validation: │
│ - Document input validation rules │
│ - Document required fields │
│ - Document field constraints │
└─────────────────────────────────────────────────────────────┘
API Documentation Tools
Popular Tools
┌─────────────────────────────────────────────────────────────┐
│ API Documentation Tools │
├─────────────────────────────────────────────────────────────┤
│ Swagger UI: │
│ - Interactive API documentation │
│ - OpenAPI support │
│ - Customizable │
│ - Self-hosted │
│ │
│ Redoc: │
│ - Beautiful documentation │
│ - OpenAPI support │
│ - Custom themes │
│ - CLI integration │
│ │
│ Postman Documentation: │
│ - Collection documentation │
│ - Interactive examples │
│ - Team collaboration │
│ - API monitoring │
│ │
│ Slate: │
│ - Markdown-based │
│ - Easy to customize │
│ - Static site generation │
│ - Multiple languages │
│ │
│ Stoplight: │
│ - OpenAPI editor │
│ - Documentation generation │
│ - Mock servers │
│ - Testing tools │
└─────────────────────────────────────────────────────────────┘
API Documentation Checklist
Documentation Checklist
┌─────────────────────────────────────────────────────────────┐
│ API Documentation Checklist │
├─────────────────────────────────────────────────────────────┤
│ General: │
│ [ ] API overview and purpose │
│ [ ] Authentication requirements │
│ [ ] API versioning information │
│ [ ] Base URL information │
│ │
│ Endpoints: │
│ [ ] All endpoints documented │
│ [ ] HTTP methods documented │
│ [ ] Request parameters documented │
│ [ ] Request body documented │
│ [ ] Response examples provided │
│ [ ] Error responses documented │
│ │
│ Examples: │
│ [ ] Request examples │
│ [ ] Response examples │
│ [ ] Error examples │
│ [ ] Code examples │
│ │
│ Security: │
│ [ ] Authentication documented │
│ [ ] Authorization documented │
│ [ ] Rate limiting documented │
│ [ ] Security headers documented │
│ │
│ Advanced Features: │
│ [ ] Pagination documented │
│ [ ] Filtering documented │
│ [ ] Sorting documented │
│ [ ] Including related resources documented │
└─────────────────────────────────────────────────────────────┘
Real-World Impact
Before this skill:
- Incomplete API documentation
- Missing examples
- Poor API discoverability
- Developer frustration
- Support overhead
After this skill:
- Comprehensive API documentation
- Clear examples
- Easy API discoverability
- Developer satisfaction
- Reduced support overhead
Cross-References
api-design - For API design and specificationsdocumentation-best-practices - For documentation standardscontext7-docs - For up-to-date documentation
References
