Qwen3-4B-Thinking-2507-GPT-5-Codex-Distill-GGUF实战教程：从零搭建API文档自动化系统
本文介绍了如何利用星图GPU平台，自动化部署Qwen3-4B-Thinking-2507-GPT-5-Codex-Distill-GGUF镜像，快速搭建API文档与Mock Server自动化生成系统。该方案能将自然语言描述的接口需求，自动转换为规范的Swagger文档和可运行的FastAPI代码，极大提升后端开发与前后端协作效率。
·
Qwen3-4B-Thinking-2507-GPT-5-Codex-Distill-GGUF实战教程：从零搭建API文档自动化系统
1. 引言：为什么你需要API文档自动化
如果你是一名后端开发者，下面这个场景你一定不陌生：项目进入联调阶段，前端同事跑过来问：“这个用户列表接口的响应字段是什么？分页参数怎么传？”你一边翻代码，一边在聊天窗口里打字解释，然后突然想起来：“哦对了，Swagger文档还没更新。”
更麻烦的是，为了让前端能提前开发，你还需要搭建一个Mock Server来模拟接口返回。于是你打开另一个编辑器，开始写模拟数据、定义路由、处理请求参数……等这些都弄好，半天时间过去了。
手动维护API文档和Mock Server，就像在沙滩上建城堡——代码一改，文档就过时；需求一变，Mock数据就对不上。这种重复、琐碎、易错的工作，真的值得你花那么多时间吗？
今天，我要分享一个完全不同的思路：用AI自动生成这一切。借助Qwen3-4B-Thinking-2507-GPT-5-Codex-Distill-GGUF模型，你只需要描述清楚接口是干什么的，AI就能给你生成完整的Swagger文档和可运行的Mock Server代码。
这个模型在OpenAI GPT-5-Codex的1000个代码示例上专门训练过，特别擅长理解编程需求、生成结构化的代码和文档。接下来，我会手把手带你搭建一个完整的自动化系统，让你从此告别手动写文档的烦恼。
2. 环境准备：快速部署你的AI助手
2.1 模型特点：为什么选择这个模型
在开始之前，我们先了解一下Qwen3-4B-Thinking-2507-GPT-5-Codex-Distill-GGUF模型有什么特别之处：
- 代码理解能力强：它能准确理解“获取用户分页列表”这样的自然语言描述，并转换成具体的接口定义
- 结构化输出优秀：生成的Swagger文档格式规范，Mock代码结构清晰，开箱即用
- 上下文感知：如果你先让它生成用户接口，再让它生成订单接口，它会记得之前的用户模型定义
- 多语言支持：虽然我们主要用Python，但它也擅长JavaScript、Java等其他语言
简单说，这就是一个专门为代码相关任务优化的AI助手。它不会跟你闲聊天气，但能帮你搞定各种编程文档和代码生成任务。
2.2 三步完成模型部署
部署过程比你想的要简单。这个模型已经用vLLM打包好了，你只需要确认服务正常运行就行。
首先，打开终端，检查模型是否加载成功：
# 查看模型服务日志
cat /root/workspace/llm.log
如果看到类似“Model loaded successfully”这样的信息，说明模型已经准备好了。
接下来，我们需要一个简单的方式来测试模型。这里用Chainlit作为前端界面，它就像个聊天窗口，你可以直接跟模型对话。
打开Chainlit界面，输入一个简单的测试问题：
请用Python写一个获取用户信息的接口，包含id、name、email字段
如果模型能返回完整的FastAPI或Flask代码，包括路由定义、参数验证和响应模型，那就说明一切正常。这个过程通常只需要几秒钟。
3. 核心工具：设计你的提示词模板
3.1 理解提示词：告诉AI你想要什么
让AI生成准确的内容，关键是要给它清晰的指令。这就好比点菜——你不能只说“来点吃的”，而要说“来一份宫保鸡丁，微辣，不要花生”。
对于API文档生成，我们需要设计专门的提示词模板。这个模板要告诉AI三件事：
- 我们需要什么格式（Swagger YAML）
- 需要包含哪些信息（接口路径、参数、响应等）
- 用什么风格和规范
下面是一个基础的模板，你可以直接复制使用：
# Swagger文档生成提示词模板
SWAGGER_PROMPT_TEMPLATE = """
请根据以下接口描述，生成完整的Swagger/OpenAPI 3.0文档。
接口基本信息：
- 接口名称：{api_name}
- 接口路径：{api_path}
- 请求方法：{http_method}
- 功能描述：{api_description}
详细参数说明：
{request_params}
响应数据结构：
{response_example}
具体要求：
1. 使用YAML格式输出，符合OpenAPI 3.0规范
2. 包含完整的paths和components定义
3. 每个参数都要有详细的description说明用途
4. 响应要包含200成功状态码和示例数据
5. 如果有枚举值（比如status字段），要明确列出可选值
6. 数字字段要标注最小值、最大值限制
7. 直接输出文档，不要额外解释文字
现在开始生成：
"""
这个模板就像个填空题，你把接口信息填进去，AI就能输出规范的Swagger文档。
3.2 进阶技巧：让生成结果更符合你的需求
如果你对生成结果有特殊要求，可以在模板里添加更多细节。比如：
# 带项目特定要求的模板
ADVANCED_SWAGGER_PROMPT = """
请为我们的电商项目生成Swagger文档，要求如下：
项目规范：
1. 所有接口路径以/api/v1/开头
2. 响应统一格式：{"code": 200, "message": "success", "data": {}}
3. 分页参数统一用page和page_size
4. 时间字段统一用ISO 8601格式：YYYY-MM-DDTHH:MM:SSZ
5. 错误码定义：400参数错误，401未授权，404资源不存在，500服务器错误
接口信息：
{接口信息填充处}
请严格按照以上规范生成。
"""
越详细的提示词，生成的结果就越符合你的预期。刚开始可以简单点，后面根据需求慢慢完善。
4. 实战演练：从零生成用户管理API
4.1 第一步：准备接口描述
让我们从一个实际的用户管理接口开始。假设我们需要一个“获取用户列表”的接口，支持分页和条件筛选。
# 定义接口信息
user_list_api = {
"api_name": "获取用户列表",
"api_path": "/api/v1/users",
"http_method": "GET",
"api_description": "分页查询用户列表，可以根据用户名模糊搜索，也可以按状态筛选",
"request_params": """
查询参数说明：
- page: 页码，整数类型，从1开始，不传默认为1
- page_size: 每页条数，整数类型，范围1-100，不传默认为20
- username: 用户名关键词，字符串类型，用于模糊搜索，可选
- status: 用户状态，字符串类型，只能填'active'或'inactive'，可选
- created_at_start: 创建时间开始，日期时间格式，可选
- created_at_end: 创建时间结束，日期时间格式，可选
""",
"response_example": """
成功响应示例：
{
"code": 200,
"message": "success",
"data": {
"total": 156,
"page": 1,
"page_size": 20,
"users": [
{
"id": 1,
"username": "zhangsan",
"email": "zhangsan@example.com",
"phone": "13800138000",
"status": "active",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-03-20T14:25:00Z"
},
{
"id": 2,
"username": "lisi",
"email": "lisi@company.com",
"phone": "13900139000",
"status": "inactive",
"created_at": "2024-02-10T09:15:00Z",
"updated_at": "2024-03-18T11:40:00Z"
}
]
}
}
错误响应示例：
{
"code": 400,
"message": "参数验证失败：page_size不能超过100",
"data": null
}
"""
}
注意看，我把接口描述得很详细：每个参数是什么类型、有什么限制、是否必填、默认值是多少。响应示例也包含了成功和错误两种情况。信息越完整，AI生成的结果就越准确。
4.2 第二步：调用AI生成Swagger文档
有了接口描述和提示词模板，现在可以调用模型了：
import requests
import yaml
def generate_swagger_doc(api_info, model_endpoint="http://localhost:8000/v1/completions"):
"""
调用AI模型生成Swagger文档
Args:
api_info: 接口信息字典
model_endpoint: 模型服务地址
Returns:
生成的Swagger文档（YAML字符串）
"""
# 填充提示词模板
prompt = SWAGGER_PROMPT_TEMPLATE.format(**api_info)
# 调用模型
response = requests.post(
model_endpoint,
json={
"prompt": prompt,
"max_tokens": 2000, # 控制生成长度
"temperature": 0.3, # 控制随机性，值越低输出越稳定
"stop": ["```", "---"] # 停止标记，防止多余输出
},
timeout=30
)
if response.status_code == 200:
result = response.json()
swagger_yaml = result["text"].strip()
# 验证生成的YAML是否有效
try:
yaml.safe_load(swagger_yaml)
print("✅ Swagger文档生成成功，格式验证通过")
return swagger_yaml
except yaml.YAMLError as e:
print(f"❌ 生成的YAML格式有误：{e}")
# 可以尝试修复或重新生成
return None
else:
print(f"❌ 模型调用失败：{response.status_code}")
return None
# 执行生成
swagger_yaml = generate_swagger_doc(user_list_api)
if swagger_yaml:
print("生成的Swagger文档：")
print(swagger_yaml)
运行这段代码，你会得到完整的Swagger YAML文档。AI生成的内容通常包括：
- 完整的OpenAPI 3.0头部信息
- 详细的接口路径定义
- 每个参数的schema定义
- 响应模型和示例
- 可复用的components定义
4.3 第三步：基于Swagger生成Mock Server
有了Swagger文档，下一步就是生成可运行的Mock Server代码。我们继续使用AI来完成这个任务：
# Mock Server生成提示词模板
MOCK_SERVER_PROMPT = """
请根据以下Swagger文档，生成一个完整的FastAPI Mock Server。
具体要求：
1. 使用FastAPI框架，这是目前最流行的Python Web框架
2. 为每个接口实现Mock逻辑，返回符合schema的模拟数据
3. 模拟数据要看起来真实（比如用户名用常见名字，邮箱符合格式）
4. 包含完整的错误处理（参数验证、服务器错误等）
5. 添加CORS支持，方便前端调用
6. 代码要有清晰的注释，方便其他人理解
7. 添加一个/health接口用于健康检查
8. 使用Python 3.9+的语法特性
Swagger文档内容：
{swagger_content}
请直接输出完整的Python代码，以```python开头，以```结尾。
"""
def generate_mock_server(swagger_yaml, model_endpoint="http://localhost:8000/v1/completions"):
"""
生成Mock Server代码
Args:
swagger_yaml: Swagger文档内容
model_endpoint: 模型服务地址
Returns:
生成的Python代码
"""
prompt = MOCK_SERVER_PROMPT.format(swagger_content=swagger_yaml)
response = requests.post(
model_endpoint,
json={
"prompt": prompt,
"max_tokens": 3000, # Mock代码可能较长
"temperature": 0.2, # 代码生成需要更稳定
"stop": ["```"] # 代码块结束标记
},
timeout=45
)
if response.status_code == 200:
result = response.json()
code = result["text"].strip()
# 提取代码块内容
if code.startswith("```python"):
code = code[9:] # 去掉```python
if code.endswith("```"):
code = code[:-3] # 去掉结尾的```
print("✅ Mock Server代码生成成功")
return code.strip()
else:
print(f"❌ 生成失败：{response.status_code}")
return None
# 生成Mock Server
mock_code = generate_mock_server(swagger_yaml)
if mock_code:
# 保存到文件
with open("mock_server.py", "w", encoding="utf-8") as f:
f.write(mock_code)
print("📁 Mock Server代码已保存到 mock_server.py")
# 预览前几行
print("\n生成的代码预览：")
print(mock_code[:500] + "...")
生成的代码通常会包括：
- FastAPI应用实例和CORS配置
- Pydantic数据模型定义
- 模拟数据生成函数
- 完整的接口实现
- 错误处理中间件
- 健康检查接口
- 启动脚本
4.4 第四步：运行和测试你的Mock Server
代码生成后，直接运行就能启动Mock Server：
# 安装依赖（如果还没有安装）
pip install fastapi uvicorn pydantic
# 运行Mock Server
python mock_server.py
服务启动后，打开浏览器访问 http://localhost:8000/docs，你会看到自动生成的Swagger UI界面。在这里你可以：
- 查看所有接口的文档
- 直接测试接口
- 查看请求和响应的结构
试着调用一下用户列表接口：
GET http://localhost:8000/api/v1/users?page=1&page_size=10
你会得到类似这样的响应：
{
"code": 200,
"message": "success",
"data": {
"total": 100,
"page": 1,
"page_size": 10,
"users": [
{
"id": 1,
"username": "user_1",
"email": "user1@example.com",
"phone": "13800138001",
"status": "active",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-03-20T14:25:00Z"
},
// ... 更多用户数据
]
}
}
前端同事现在就可以用这个Mock Server进行开发了，完全不需要等待后端接口真正实现。
5. 批量处理：一键生成整个项目的API
5.1 设计批量生成脚本
实际项目中通常有几十个甚至上百个接口，一个一个生成太麻烦。我们可以写个脚本批量处理：
import os
import json
import yaml
from datetime import datetime
from typing import List, Dict, Any
class BatchAPIGenerator:
"""批量API文档生成器"""
def __init__(self, model_endpoint: str, output_dir: str = "./api_docs"):
"""
初始化生成器
Args:
model_endpoint: 模型服务地址
output_dir: 输出目录
"""
self.model_endpoint = model_endpoint
self.output_dir = output_dir
os.makedirs(output_dir, exist_ok=True)
# 创建子目录
self.swagger_dir = os.path.join(output_dir, "swagger")
self.mock_dir = os.path.join(output_dir, "mock_servers")
self.schemas_dir = os.path.join(output_dir, "schemas")
for dir_path in [self.swagger_dir, self.mock_dir, self.schemas_dir]:
os.makedirs(dir_path, exist_ok=True)
def load_api_definitions(self, definition_file: str) -> List[Dict[str, Any]]:
"""
从JSON文件加载API定义
Args:
definition_file: API定义文件路径
Returns:
API定义列表
"""
with open(definition_file, 'r', encoding='utf-8') as f:
definitions = json.load(f)
print(f"📋 加载了 {len(definitions)} 个API定义")
return definitions
def generate_single_api(self, api_def: Dict[str, Any]) -> Dict[str, str]:
"""
生成单个API的文档和代码
Args:
api_def: 单个API的定义
Returns:
包含生成结果的字典
"""
api_name = api_def.get("name", "unknown")
print(f"🔄 正在处理: {api_name}")
results = {}
try:
# 1. 生成Swagger文档
swagger_prompt = SWAGGER_PROMPT_TEMPLATE.format(**api_def)
swagger_yaml = self._call_model(swagger_prompt, max_tokens=2500)
if swagger_yaml:
results["swagger"] = swagger_yaml
# 2. 生成Mock Server代码
mock_prompt = MOCK_SERVER_PROMPT.format(swagger_content=swagger_yaml)
mock_code = self._call_model(mock_prompt, max_tokens=3500)
if mock_code:
results["mock_server"] = mock_code
# 3. 生成TypeScript类型定义（可选）
ts_prompt = self._create_ts_prompt(swagger_yaml)
ts_types = self._call_model(ts_prompt, max_tokens=1500)
if ts_types:
results["typescript"] = ts_types
print(f"✅ 完成: {api_name}")
else:
print(f"❌ 失败: {api_name} - Swagger生成失败")
except Exception as e:
print(f"❌ 处理 {api_name} 时出错: {str(e)}")
return results
def _call_model(self, prompt: str, max_tokens: int = 2000) -> str:
"""调用模型生成内容"""
try:
response = requests.post(
self.model_endpoint,
json={
"prompt": prompt,
"max_tokens": max_tokens,
"temperature": 0.3,
"stop": ["```", "---", "\n\n\n"]
},
timeout=60
)
if response.status_code == 200:
result = response.json()
text = result["text"].strip()
# 清理输出
if text.startswith("```"):
lines = text.split("\n")
if len(lines) > 1 and lines[0].startswith("```"):
text = "\n".join(lines[1:-1]) if lines[-1] == "```" else "\n".join(lines[1:])
return text
else:
print(f"模型调用失败: {response.status_code}")
return None
except requests.exceptions.Timeout:
print("模型调用超时")
return None
except Exception as e:
print(f"模型调用异常: {str(e)}")
return None
def _create_ts_prompt(self, swagger_yaml: str) -> str:
"""创建TypeScript类型生成提示词"""
return f"""
请根据以下Swagger文档，生成对应的TypeScript类型定义。
要求：
1. 为每个Schema生成对应的interface
2. 为每个API生成请求参数和响应类型
3. 使用export导出所有类型
4. 添加必要的注释说明
5. 使用更严格的类型（比如用字面量类型代替string）
Swagger文档：
{swagger_yaml}
请直接输出TypeScript代码，以```typescript开头。
"""
def batch_generate(self, api_definitions: List[Dict[str, Any]]):
"""批量生成所有API"""
all_results = {}
for api_def in api_definitions:
api_name = api_def.get("name", f"api_{datetime.now().timestamp()}")
safe_name = api_name.replace("/", "_").replace(":", "")
results = self.generate_single_api(api_def)
if results:
all_results[api_name] = results
# 保存到文件
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
# 保存Swagger文档
if "swagger" in results:
swagger_file = os.path.join(
self.swagger_dir,
f"{safe_name}_{timestamp}.yaml"
)
with open(swagger_file, 'w', encoding='utf-8') as f:
f.write(results["swagger"])
# 保存Mock Server代码
if "mock_server" in results:
mock_file = os.path.join(
self.mock_dir,
f"{safe_name}_mock_{timestamp}.py"
)
with open(mock_file, 'w', encoding='utf-8') as f:
f.write(results["mock_server"])
# 保存TypeScript类型
if "typescript" in results:
ts_file = os.path.join(
self.schemas_dir,
f"{safe_name}_types_{timestamp}.ts"
)
with open(ts_file, 'w', encoding='utf-8') as f:
f.write(results["typescript"])
# 生成汇总报告
self._generate_report(all_results)
return all_results
def _generate_report(self, results: Dict[str, Dict]):
"""生成生成报告"""
report = {
"generated_at": datetime.now().isoformat(),
"total_apis": len(results),
"success_count": sum(1 for r in results.values() if r),
"details": {}
}
for api_name, api_results in results.items():
report["details"][api_name] = {
"has_swagger": "swagger" in api_results,
"has_mock": "mock_server" in api_results,
"has_types": "typescript" in api_results
}
report_file = os.path.join(self.output_dir, "generation_report.json")
with open(report_file, 'w', encoding='utf-8') as f:
json.dump(report, f, indent=2, ensure_ascii=False)
print(f"\n📊 生成报告已保存: {report_file}")
print(f"总计处理: {report['total_apis']} 个API")
print(f"成功生成: {report['success_count']} 个")
# 使用示例
if __name__ == "__main__":
# 初始化生成器
generator = BatchAPIGenerator(
model_endpoint="http://localhost:8000/v1/completions",
output_dir="./generated_apis"
)
# 加载API定义（可以从文件或数据库读取）
api_definitions = [
{
"name": "获取用户列表",
"api_path": "/api/v1/users",
"http_method": "GET",
# ... 其他定义
},
{
"name": "创建用户",
"api_path": "/api/v1/users",
"http_method": "POST",
# ... 其他定义
},
# ... 更多API定义
]
# 批量生成
results = generator.batch_generate(api_definitions)
print(f"\n🎉 批量生成完成！")
print(f"查看生成结果: ls -la {generator.output_dir}/")
5.2 API定义文件格式
为了让批量处理更方便，我们可以定义统一的API描述格式：
[
{
"name": "获取用户列表",
"api_path": "/api/v1/users",
"http_method": "GET",
"api_description": "分页查询用户列表，支持条件筛选",
"request_params": "page: 页码，从1开始\npage_size: 每页数量，1-100\nusername: 用户名模糊搜索\nstatus: 用户状态，active或inactive",
"response_example": "{\"code\": 200, \"message\": \"success\", \"data\": {\"total\": 100, \"page\": 1, \"page_size\": 20, \"users\": []}}",
"tags": ["用户管理"],
"security": ["BearerAuth"]
},
{
"name": "创建用户",
"api_path": "/api/v1/users",
"http_method": "POST",
"api_description": "创建新用户",
"request_params": "username: 用户名，必填\nemail: 邮箱，必填\nphone: 手机号，可选\npassword: 密码，必填",
"request_body_example": "{\"username\": \"testuser\", \"email\": \"test@example.com\", \"password\": \"123456\"}",
"response_example": "{\"code\": 201, \"message\": \"用户创建成功\", \"data\": {\"id\": 1, \"username\": \"testuser\", \"email\": \"test@example.com\"}}",
"tags": ["用户管理"],
"security": ["BearerAuth"]
},
{
"name": "获取订单详情",
"api_path": "/api/v1/orders/{order_id}",
"http_method": "GET",
"api_description": "根据订单ID获取订单详细信息",
"path_params": "order_id: 订单ID，字符串格式",
"response_example": "{\"code\": 200, \"message\": \"success\", \"data\": {\"id\": \"ORD202401010001\", \"total_amount\": 299.99, \"status\": \"paid\", \"items\": []}}",
"tags": ["订单管理"],
"security": ["BearerAuth"]
}
]
把这个JSON文件保存为 api_definitions.json，然后运行批量生成脚本，就能一次性生成所有接口的文档和Mock代码。
6. 高级技巧：优化生成效果
6.1 处理复杂场景
有时候接口比较复杂，比如有嵌套对象、数组、联合类型等。这时候需要更详细的描述：
# 复杂接口的详细描述
complex_api = {
"name": "批量创建订单",
"api_path": "/api/v1/orders/batch",
"http_method": "POST",
"api_description": "批量创建多个订单，支持不同的收货地址和支付方式",
"request_body_example": """
{
"orders": [
{
"user_id": 123,
"items": [
{
"product_id": "P001",
"quantity": 2,
"price": 99.99
},
{
"product_id": "P002",
"quantity": 1,
"price": 199.99
}
],
"shipping_address": {
"name": "张三",
"phone": "13800138000",
"province": "北京市",
"city": "北京市",
"district": "朝阳区",
"detail": "某某路123号"
},
"payment_method": "alipay",
"remarks": "请尽快发货"
}
],
"create_options": {
"validate_only": false,
"notify_user": true,
"source": "web"
}
}
""",
"response_example": """
{
"code": 200,
"message": "批量创建成功",
"data": {
"success_count": 1,
"failed_count": 0,
"results": [
{
"index": 0,
"success": true,
"order_id": "ORD202403200001",
"message": "创建成功"
}
],
"summary": {
"total_amount": 299.97,
"total_items": 3
}
}
}
"""
}
对于这种复杂接口，AI可能需要更多上下文。你可以分两步生成：
def generate_complex_api_step_by_step(api_def):
"""分步生成复杂API的文档"""
# 第一步：先生成数据模型
schema_prompt = """
请根据以下JSON示例，生成对应的OpenAPI Schema定义。
JSON示例：
{json_example}
要求：
1. 分析JSON结构，定义所有必要的Schema
2. 为每个字段添加类型和描述
3. 处理嵌套对象和数组
4. 添加必要的验证规则（如必填字段、枚举值等）
请只输出Schema定义部分。
""".format(json_example=api_def["request_body_example"])
# 调用模型生成Schema
schemas = call_model(schema_prompt)
# 第二步：生成完整接口文档
full_prompt = f"""
请生成完整的API文档，包括：
接口基本信息：
- 路径：{api_def['api_path']}
- 方法：{api_def['http_method']}
- 描述：{api_def['api_description']}
请求体Schema（已生成）：
{schemas}
响应示例：
{api_def['response_example']}
请生成完整的OpenAPI 3.0文档。
"""
return call_model(full_prompt)
6.2 质量检查和修复
AI生成的内容偶尔会有小问题，我们可以添加自动检查：
import re
import json
import yaml
def validate_and_fix_swagger(swagger_yaml: str) -> str:
"""
验证并修复Swagger文档
Args:
swagger_yaml: 生成的Swagger YAML
Returns:
修复后的Swagger YAML
"""
try:
# 尝试解析YAML
doc = yaml.safe_load(swagger_yaml)
# 检查必要字段
required_fields = ["openapi", "info", "paths"]
for field in required_fields:
if field not in doc:
print(f"⚠️ 缺少必要字段: {field}")
# 尝试修复
if field == "openapi":
doc["openapi"] = "3.0.3"
elif field == "info":
doc["info"] = {"title": "API文档", "version": "1.0.0"}
# 检查paths是否为空
if not doc.get("paths"):
print("⚠️ paths字段为空")
doc["paths"] = {}
# 重新生成YAML
fixed_yaml = yaml.dump(doc, allow_unicode=True, sort_keys=False)
return fixed_yaml
except yaml.YAMLError as e:
print(f"❌ YAML解析错误: {e}")
# 尝试修复常见的YAML格式问题
fixed = swagger_yaml
# 修复缩进问题
fixed = re.sub(r'^\s+', ' ', fixed, flags=re.MULTILINE)
# 修复冒号后缺少空格的问题
fixed = re.sub(r':(\S)', r': \1', fixed)
# 尝试再次解析
try:
yaml.safe_load(fixed)
print("✅ 自动修复成功")
return fixed
except:
print("❌ 自动修复失败，返回原始内容")
return swagger_yaml
def validate_mock_code(mock_code: str) -> str:
"""
验证并修复Mock Server代码
Args:
mock_code: 生成的Python代码
Returns:
修复后的代码
"""
# 检查必要的导入
required_imports = [
"from fastapi import",
"import uvicorn"
]
for imp in required_imports:
if imp not in mock_code:
print(f"⚠️ 缺少必要导入: {imp}")
# 在文件开头添加
if "from fastapi import" not in mock_code:
mock_code = "from fastapi import FastAPI, HTTPException\n" + mock_code
# 检查是否有app定义
if "app = FastAPI" not in mock_code:
print("⚠️ 缺少FastAPI应用实例")
# 尝试添加
lines = mock_code.split('\n')
for i, line in enumerate(lines):
if "import" in line and "fastapi" in line:
lines.insert(i + 1, "\napp = FastAPI()")
mock_code = '\n'.join(lines)
break
# 检查是否有启动代码
if "__name__ == \"__main__\"" not in mock_code:
print("⚠️ 缺少启动代码")
mock_code += "\n\nif __name__ == \"__main__\":\n uvicorn.run(app, host=\"0.0.0.0\", port=8000)"
return mock_code
6.3 性能优化建议
如果项目有很多接口，生成时间可能会比较长。这里有几个优化建议：
- 并行生成：使用多线程或异步请求同时生成多个接口
- 缓存结果：对相同的接口描述缓存生成结果
- 增量更新：只重新生成有变化的接口
- 预处理模板：把常用的代码片段预定义为模板
import concurrent.futures
from typing import List, Dict
def parallel_generate(api_definitions: List[Dict], max_workers: int = 3):
"""并行生成多个API文档"""
def generate_one(api_def):
"""单个API的生成任务"""
try:
swagger = generate_swagger_doc(api_def)
if swagger:
mock = generate_mock_server(swagger)
return {
"name": api_def.get("name"),
"swagger": swagger,
"mock": mock,
"success": True
}
except Exception as e:
print(f"生成失败 {api_def.get('name')}: {e}")
return {
"name": api_def.get("name"),
"success": False
}
# 使用线程池并行处理
with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
futures = [executor.submit(generate_one, api_def) for api_def in api_definitions]
results = []
for future in concurrent.futures.as_completed(futures):
result = future.result()
results.append(result)
print(f"完成: {result['name']} - {'成功' if result['success'] else '失败'}")
return results
7. 集成到开发流程
7.1 与Git集成
我们可以把API文档生成集成到Git工作流中，每次提交代码时自动更新文档：
# .gitlab-ci.yml 或 .github/workflows/api-docs.yml
name: Generate API Documentation
on:
push:
branches: [main, develop]
paths:
- 'src/apis/**' # 监控API定义文件变化
pull_request:
branches: [main]
jobs:
generate-docs:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.9'
- name: Install dependencies
run: |
pip install requests pyyaml
- name: Generate API documentation
env:
MODEL_ENDPOINT: ${{ secrets.MODEL_ENDPOINT }}
run: |
python scripts/generate_api_docs.py \
--model-endpoint $MODEL_ENDPOINT \
--api-defs src/apis/definitions/ \
--output-dir docs/api/ \
--format both # 生成Swagger和Mock代码
- name: Deploy to GitHub Pages
if: github.ref == 'refs/heads/main'
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs/api/
destination_dir: ./api-docs
7.2 创建开发助手脚本
为了方便日常使用，我们可以创建一个命令行工具：
#!/usr/bin/env python3
"""
API文档生成命令行工具
"""
import argparse
import sys
from pathlib import Path
def main():
parser = argparse.ArgumentParser(description="API文档自动生成工具")
parser.add_argument(
"action",
choices=["generate", "validate", "serve", "test"],
help="执行的操作"
)
parser.add_argument(
"--input",
"-i",
type=str,
help="输入文件或目录路径"
)
parser.add_argument(
"--output",
"-o",
type=str,
default="./output",
help="输出目录路径"
)
parser.add_argument(
"--model",
"-m",
type=str,
default="http://localhost:8000/v1/completions",
help="模型服务地址"
)
parser.add_argument(
"--format",
"-f",
choices=["swagger", "mock", "both", "all"],
default="both",
help="生成格式"
)
args = parser.parse_args()
if args.action == "generate":
from api_generator import BatchAPIGenerator
if not args.input:
print("错误：需要指定输入文件")
sys.exit(1)
generator = BatchAPIGenerator(
model_endpoint=args.model,
output_dir=args.output
)
# 根据输入类型处理
input_path = Path(args.input)
if input_path.is_file():
# 单个文件
if input_path.suffix == ".json":
import json
with open(input_path, 'r') as f:
api_defs = json.load(f)
if isinstance(api_defs, dict):
api_defs = [api_defs]
else:
print("错误：只支持JSON文件")
sys.exit(1)
else:
# 目录，查找所有JSON文件
json_files = list(input_path.glob("**/*.json"))
api_defs = []
for json_file in json_files:
import json
with open(json_file, 'r') as f:
data = json.load(f)
if isinstance(data, list):
api_defs.extend(data)
else:
api_defs.append(data)
print(f"找到 {len(api_defs)} 个API定义")
results = generator.batch_generate(api_defs)
success_count = sum(1 for r in results.values() if r.get("success", False))
print(f"\n✅ 生成完成！成功: {success_count}/{len(api_defs)}")
elif args.action == "serve":
# 启动Mock Server
import subprocess
import os
mock_dir = Path(args.output) / "mock_servers"
if not mock_dir.exists():
print(f"错误：Mock目录不存在 {mock_dir}")
sys.exit(1)
# 查找最新的Mock Server文件
mock_files = list(mock_dir.glob("*.py"))
if not mock_files:
print("错误：没有找到Mock Server文件")
sys.exit(1)
latest_file = max(mock_files, key=lambda p: p.stat().st_mtime)
print(f"启动Mock Server: {latest_file}")
# 切换到文件所在目录
os.chdir(latest_file.parent)
subprocess.run([sys.executable, latest_file.name])
elif args.action == "validate":
# 验证生成的文档
from validators import validate_all_docs
validate_all_docs(args.output)
elif args.action == "test":
# 测试API端点
from test_runner import run_api_tests
run_api_tests(args.input, args.model)
if __name__ == "__main__":
main()
使用这个工具：
# 生成API文档
python api_tool.py generate -i apis/user_management.json -o ./docs
# 启动Mock Server
python api_tool.py serve -o ./docs
# 验证生成的文档
python api_tool.py validate -o ./docs
# 测试API端点
python api_tool.py test -i apis/ -m http://localhost:8000/v1/completions
8. 总结
8.1 核心价值回顾
通过这个教程，我们实现了一个完整的API文档自动化系统。回顾一下我们做了什么：
- 部署了专门的代码生成模型：Qwen3-4B-Thinking-2507-GPT-5-Codex-Distill-GGUF，一个专门为代码任务优化的AI助手
- 设计了智能的提示词模板：告诉AI我们需要什么格式的文档和代码
- 实现了从描述到文档的自动化：输入自然语言描述，输出规范的Swagger文档
- 生成了可运行的Mock Server：基于Swagger文档，自动生成完整的FastAPI应用
- 支持批量处理：一次生成整个项目的所有API文档
- 集成了质量检查：自动验证和修复生成的内容
- 创建了命令行工具：方便集成到开发工作流中
8.2 实际效果评估
在实际使用中，这个方案带来了几个明显的好处：
效率提升最明显：原来需要几个小时手动编写的文档和Mock代码，现在几分钟就能生成。特别是新项目启动时，几十个接口的文档和Mock服务一次性搞定，前端可以立即开始对接。
一致性有保障：AI生成的文档和代码始终保持一致，不会出现“文档说返回A，代码实际返回B”的问题。接口有变动时，重新生成一下就行。
质量相当不错：生成的Swagger文档符合OpenAPI 3.0规范，Mock代码结构清晰，包含了错误处理、数据验证等生产级功能。
学习成本低：不需要学习复杂的文档编写语法，用自然语言描述接口就行。对新手特别友好。
8.3 使用建议和注意事项
根据我的使用经验，给你几个实用建议：
从小处开始：先从一个简单的接口试起，看看生成效果。满意了再扩展到整个项目。
完善你的提示词：AI的表现很大程度上取决于提示词的质量。多花点时间优化提示词模板，后面会省很多事。
人工检查很重要：虽然AI生成的质量不错，但重要接口还是建议人工检查一下。特别是涉及业务逻辑复杂、安全要求高的接口。
建立规范：在团队中统一API描述格式、响应格式、错误处理方式。这样AI生成的结果会更一致。
版本管理：生成的文档和代码要纳入版本管理。每次接口变更，重新生成并提交更新。
性能考虑：如果接口很多，考虑使用并行生成和缓存。也可以把常用的代码片段预定义为模板，减少AI的生成量。
8.4 扩展思路
这个基础方案还可以进一步扩展：
支持更多框架：除了FastAPI，还可以生成Flask、Django、Spring Boot等框架的代码。
生成客户端SDK：基于Swagger文档，自动生成各种语言的客户端SDK（Python、JavaScript、Java等）。
集成测试用例：自动生成接口测试用例，包括正常场景和异常场景。
文档网站生成：把Swagger文档转换成漂亮的文档网站，方便团队查阅。
与数据库结合：从数据库表结构自动生成CRUD接口的文档和代码。
技术应该让我们的生活更轻松，而不是更复杂。API文档和Mock Server这种重复性工作，正是AI擅长的领域。把时间省下来，去思考更有价值的架构设计、业务逻辑优化，这才是技术人该做的事。
希望这个教程能帮你从繁琐的文档工作中解放出来。如果你在实践过程中有任何问题，或者有更好的想法，欢迎交流分享。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。
更多推荐
0
0- 0
已为社区贡献13条内容
所有评论(0)