api-documentation by supercent-io/skills-template
npx skills add https://github.com/supercent-io/skills-template --skill api-documentationopenapi: 3.0.0
info:
title: User Management API
version: 1.0.0
description: API for managing users
contact:
email: api@example.com
servers:
- url: https://api.example.com/v1
description: Production
- url: https://staging-api.example.com/v1
description: Staging
paths:
/users:
get:
summary: List all users
description: Retrieve a paginated list of users
tags:
- Users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 100
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
$ref: '#/components/responses/Unauthorized'
post:
summary: Create a new user
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
email:
type: string
format: email
name:
type: string
createdAt:
type: string
format: date-time
required:
- id
- email
- name
CreateUserRequest:
type: object
properties:
email:
type: string
format: email
name:
type: string
minLength: 2
maxLength: 50
password:
type: string
minLength: 8
required:
- email
- name
- password
Pagination:
type: object
properties:
page:
type: integer
limit:
type: integer
total:
type: integer
responses:
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Authentication required"
BadRequest:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Invalid input"
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
Express + TypeScript:
/**
* @swagger
* /api/users:
* post:
* summary: Create a new user
* tags: [Users]
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - email
* - name
* - password
* properties:
* email:
* type: string
* format: email
* name:
* type: string
* password:
* type: string
* minLength: 8
* responses:
* 201:
* description: User created successfully
* 400:
* description: Invalid input
*/
router.post('/users', async (req, res) => {
const { email, name, password } = req.body;
const user = await userService.createUser({ email, name, password });
res.status(201).json(user);
});
Swagger UI 设置:
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';
const swaggerDocument = YAML.load('./openapi.yaml');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
customCss: '.swagger-ui .topbar { display: none }',
customSiteTitle: "My API Documentation"
}));
## API 文档
### 认证
所有 API 请求都需要使用 JWT 令牌进行身份验证。
#### 获取令牌
```bash
curl -X POST https://api.example.com/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "yourpassword"}'
响应:
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "..."
}
curl -X GET https://api.example.com/v1/users \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
端点:POST /v1/users
请求体:
{
"email": "john@example.com",
"name": "John Doe",
"password": "SecurePass123!"
}
成功响应 (201):
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "john@example.com",
"name": "John Doe",
"createdAt": "2025-01-15T10:00:00Z"
}
错误响应 (400):
{
"error": "Email already exists"
}
X-RateLimit-RemainingGET /v1/users?page=2&limit=20
响应包含分页信息:
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 157,
"pages": 8
}
}
400 - 错误请求(验证错误)401 - 未授权(缺少/无效令牌)403 - 禁止访问(权限不足)404 - 未找到409 - 冲突(资源重复)429 - 请求过多(超出速率限制)500 - 内部服务器错误
## 输出格式
### API 文档结构
docs/ ├── README.md # 概述 ├── getting-started.md # 快速入门指南 ├── authentication.md # 认证指南 ├── api-reference/ │ ├── users.md # 用户相关端点 │ ├── auth.md # 认证相关端点 │ └── products.md # 产品相关端点 ├── guides/ │ ├── pagination.md │ ├── error-handling.md │ └── rate-limiting.md ├── examples/ │ ├── curl.md │ ├── javascript.md │ └── python.md └── openapi.yaml # OpenAPI 规范
## 约束条件
### 必需规则 (MUST)
1. **真实示例**:提供可运行的代码示例
2. **错误情况**:不仅要记录成功情况,也要记录失败情况
3. **保持更新**:当 API 变更时更新文档
### 禁止事项 (MUST NOT)
1. **示例中使用真实密钥**:不要在示例中使用真实的 API 密钥/密码
2. **模糊描述**:避免使用像“返回数据”这样不清晰的描述
## 最佳实践
1. **试用功能**:提供交互式文档 (Swagger UI)
2. **提供 SDK**:为主要编程语言提供 SDK 和示例
3. **更新日志**:记录 API 的变更
## 参考资源
* [OpenAPI 规范](https://swagger.io/specification/)
* [Swagger UI](https://swagger.io/tools/swagger-ui/)
* [Redoc](https://redocly.com/)
## 元数据
### 版本信息
* **当前版本**:1.0.0
* **最后更新**:2025-01-01
* **兼容平台**:Claude, ChatGPT, Gemini
### 标签
`#API-documentation` `#OpenAPI` `#Swagger` `#REST` `#developer-docs` `#documentation`
## 示例
### 示例 1:基本用法
### 示例 2:高级用法
每周安装量
11.7K
代码仓库
[supercent-io/sk…template](https://github.com/supercent-io/skills-template "supercent-io/skills-template")
GitHub 星标数
88
首次出现
2026 年 1 月 24 日
安全审计
[Gen Agent Trust HubPass](/supercent-io/skills-template/api-documentation/security/agent-trust-hub)[SocketPass](/supercent-io/skills-template/api-documentation/security/socket)[SnykPass](/supercent-io/skills-template/api-documentation/security/snyk)
安装于
codex11.5K
gemini-cli11.5K
opencode11.5K
github-copilot11.5K
cursor11.5K
amp11.4K
openapi: 3.0.0
info:
title: User Management API
version: 1.0.0
description: API for managing users
contact:
email: api@example.com
servers:
- url: https://api.example.com/v1
description: Production
- url: https://staging-api.example.com/v1
description: Staging
paths:
/users:
get:
summary: List all users
description: Retrieve a paginated list of users
tags:
- Users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 100
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
$ref: '#/components/responses/Unauthorized'
post:
summary: Create a new user
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
email:
type: string
format: email
name:
type: string
createdAt:
type: string
format: date-time
required:
- id
- email
- name
CreateUserRequest:
type: object
properties:
email:
type: string
format: email
name:
type: string
minLength: 2
maxLength: 50
password:
type: string
minLength: 8
required:
- email
- name
- password
Pagination:
type: object
properties:
page:
type: integer
limit:
type: integer
total:
type: integer
responses:
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Authentication required"
BadRequest:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Invalid input"
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
Express + TypeScript :
/**
* @swagger
* /api/users:
* post:
* summary: Create a new user
* tags: [Users]
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - email
* - name
* - password
* properties:
* email:
* type: string
* format: email
* name:
* type: string
* password:
* type: string
* minLength: 8
* responses:
* 201:
* description: User created successfully
* 400:
* description: Invalid input
*/
router.post('/users', async (req, res) => {
const { email, name, password } = req.body;
const user = await userService.createUser({ email, name, password });
res.status(201).json(user);
});
Swagger UI Setup :
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';
const swaggerDocument = YAML.load('./openapi.yaml');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
customCss: '.swagger-ui .topbar { display: none }',
customSiteTitle: "My API Documentation"
}));
## API Documentation
### Authentication
All API requests require authentication using JWT tokens.
#### Getting a Token
\`\`\`bash
curl -X POST https://api.example.com/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "yourpassword"}'
\`\`\`
Response:
\`\`\`json
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "..."
}
\`\`\`
#### Using the Token
\`\`\`bash
curl -X GET https://api.example.com/v1/users \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
\`\`\`
### Creating a User
**Endpoint**: `POST /v1/users`
**Request Body**:
\`\`\`json
{
"email": "john@example.com",
"name": "John Doe",
"password": "SecurePass123!"
}
\`\`\`
**Success Response** (201):
\`\`\`json
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "john@example.com",
"name": "John Doe",
"createdAt": "2025-01-15T10:00:00Z"
}
\`\`\`
**Error Response** (400):
\`\`\`json
{
"error": "Email already exists"
}
\`\`\`
### Rate Limiting
- 100 requests per 15 minutes per IP
- Header: `X-RateLimit-Remaining`
### Pagination
\`\`\`
GET /v1/users?page=2&limit=20
\`\`\`
Response includes pagination info:
\`\`\`json
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 157,
"pages": 8
}
}
\`\`\`
### Error Codes
- `400` - Bad Request (validation error)
- `401` - Unauthorized (missing/invalid token)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `409` - Conflict (duplicate resource)
- `429` - Too Many Requests (rate limit)
- `500` - Internal Server Error
docs/
├── README.md # Overview
├── getting-started.md # Quick start guide
├── authentication.md # Auth guide
├── api-reference/
│ ├── users.md # Users endpoints
│ ├── auth.md # Auth endpoints
│ └── products.md # Products endpoints
├── guides/
│ ├── pagination.md
│ ├── error-handling.md
│ └── rate-limiting.md
├── examples/
│ ├── curl.md
│ ├── javascript.md
│ └── python.md
└── openapi.yaml # OpenAPI spec
#API-documentation #OpenAPI #Swagger #REST #developer-docs #documentation
Weekly Installs
11.7K
Repository
GitHub Stars
88
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex11.5K
gemini-cli11.5K
opencode11.5K
github-copilot11.5K
cursor11.5K
amp11.4K
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
144,300 周安装
Vue.js测试最佳实践:Vue 3组件、组合式函数、Pinia与异步测试完整指南
3,800 周安装
Google Workspace CLI 教程:使用 gws 命令创建反馈表单并邮件分享
6,400 周安装
Google Workspace CLI 团队负责人技能:自动化站会、任务协调与团队沟通工具
6,600 周安装
Google Calendar 会议重新安排技能 - 自动更新会议时间并通知参与者
6,700 周安装
PostgreSQL表设计最佳实践:核心规则、数据类型选择与常见陷阱详解
9,900 周安装
BMAD工作流编排与SSD结构化系统设计 - 多代理AI开发流程自动化
10,600 周安装