api-documentation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAPI Documentation
API文档
When to use this skill
何时使用此技能
- API 개발: 새 엔드포인트 추가 시
- 외부 공개: Public API 출시
- 팀 협업: 프론트엔드-백엔드 인터페이스 정의
- API开发：新增端点时
- 对外发布：推出公开API时
- 团队协作：定义前后端接口时
Instructions
操作步骤
Step 1: OpenAPI (Swagger) 스펙
步骤1：OpenAPI（Swagger）规范
yaml
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: []yaml
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: []Step 2: 코드에서 문서 생성 (JSDoc/Decorators)
步骤2：从代码生成文档（JSDoc/装饰器）
Express + TypeScript:
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);
});Express + TypeScript:
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);
});Step 3: 인터랙티브 문서
步骤3：交互式文档
Swagger UI 설정:
typescript
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"
}));Swagger UI配置:
typescript
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"
}));Step 4: 예제 및 가이드
步骤4：示例及指南
markdown
undefinedmarkdown
undefinedAPI Documentation
API Documentation
Authentication
认证
All API requests require authentication using JWT tokens.
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"}' ```
-H "Content-Type: application/json"
-d '{"email": "user@example.com", "password": "yourpassword"}' ```
Response:
```json
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "..."
}
```
```bash
curl -X POST https://api.example.com/v1/auth/login
-H "Content-Type: application/json"
-d '{"email": "user@example.com", "password": "yourpassword"}' ```
-H "Content-Type: application/json"
-d '{"email": "user@example.com", "password": "yourpassword"}' ```
响应:
```json
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "..."
}
```
Using the Token
使用令牌
```bash
curl -X GET https://api.example.com/v1/users
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" ```
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" ```
```bash
curl -X GET https://api.example.com/v1/users
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" ```
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" ```
Creating a User
创建用户
Endpoint:
POST /v1/usersRequest 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"
}
```
Endpoint:
POST /v1/usersRequest 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
- 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
}
}
```
```
GET /v1/users?page=2&limit=20
```
Response includes pagination info:
```json
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 157,
"pages": 8
}
}
```
Error Codes
错误码
- - Bad Request (validation error)
400 - - Unauthorized (missing/invalid token)
401 - - Forbidden (insufficient permissions)
403 - - Not Found
404 - - Conflict (duplicate resource)
409 - - Too Many Requests (rate limit)
429 - - Internal Server Error
500
undefined- - Bad Request (validation error)
400 - - Unauthorized (missing/invalid token)
401 - - Forbidden (insufficient permissions)
403 - - Not Found
404 - - Conflict (duplicate resource)
409 - - Too Many Requests (rate limit)
429 - - Internal Server Error
500
undefinedOutput format
输出格式
API 문서 구조
API文档结构
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 specdocs/
├── 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规范Constraints
约束条件
필수 규칙 (MUST)
必须遵守的规则（MUST）
- 실제 예제: 동작하는 코드 예제 제공
- 에러 케이스: 성공뿐만 아니라 실패 케이스도 문서화
- 최신 유지: API 변경 시 문서도 함께 업데이트
- 真实示例：提供可运行的代码示例
- 错误场景：不仅要记录成功场景，也要记录失败场景
- 保持更新：API变更时同步更新文档
금지 사항 (MUST NOT)
禁止事项（MUST NOT）
- 예제에 실제 키: 예제에 실제 API 키/비밀번호 사용 금지
- 모호한 설명: "데이터를 반환합니다" 같은 불명확한 설명
- 示例中使用真实密钥：禁止在示例中使用真实的API密钥/密码
- 模糊描述：避免使用“返回数据”这类不明确的描述
Best practices
最佳实践
- Try It Out: 인터랙티브 문서 제공 (Swagger UI)
- SDK 제공: 주요 언어별 SDK 및 예제
- Changelog: API 변경 사항 문서화
- Try It Out：提供交互式文档（Swagger UI）
- 提供SDK：提供主流语言的SDK及示例
- 变更日志：记录API的变更内容
References
参考资料
Metadata
元数据
버전
版本
- 현재 버전: 1.0.0
- 최종 업데이트: 2025-01-01
- 호환 플랫폼: Claude, ChatGPT, Gemini
- 当前版本：1.0.0
- 最后更新：2025-01-01
- 兼容平台：Claude, ChatGPT, Gemini
태그
标签
#API-documentation#OpenAPI#Swagger#REST#developer-docs#documentation#API-documentation#OpenAPI#Swagger#REST#developer-docs#documentationExamples
示例
Example 1: Basic usage
示例1：基础用法
<!-- Add example content here -->
<!-- Add example content here -->
Example 2: Advanced usage
示例2：高级用法
<!-- Add advanced example content here -->
<!-- Add advanced example content here -->