api-reference-documentation
使用OpenAPI规范创建专业的API文档,包括端点、认证和交互式示例。适用于记录REST API、创建SDK参考或构建开发者门户。
📖 中文导读:使用OpenAPI规范创建专业的API文档,包括端点、认证和交互式示例。适用于记录REST API、创建SDK参考或构建开发者门户。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
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
openapi: 3.0.3
info:
title: E-Commerce API
version: 1.0.0
description: API for managing products and orders
contact:
email: api@example.com
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