API 接口文档自动生成器（专业版）
输入
| 字段 | 必填 | 说明 |
|---|---|---|
| path | 是 | 如 /api/clients |
| method | 是 | GET/POST/PUT/DELETE |
| desc | 是 | 功能描述 |
| params | 否 | 请求参数dict |
输出
OpenAPI 骨架（path/operationId/parameters/responses/错误码）+ 完整性校验
Python 引擎（可独立运行）
# -*- coding: utf-8 -*-
VALID_METHODS = {"GET", "POST", "PUT", "DELETE"}
def parse_endpoint(path, method, desc, params=None):
method = method.upper()
if method not in VALID_METHODS:
raise ValueError(f"非法HTTP方法: {method}")
params = params or {}
op_id = (desc.split("。")[0].split("，")[0][:12] or path) + f"_{method.lower()}"
doc = {
"path": path, "method": method, "summary": desc,
"operationId": op_id,
"parameters": [{"name": k, "type": v.get("type", "string"),
"required": v.get("required", False)} for k, v in params.items()],
"responses": {
"200": {"description": "成功"},
"400": {"description": "参数错误"},
"500": {"description": "服务端错误"},
},
}
return doc
def validate_doc(doc, required=("path", "method", "responses")):
missing = [k for k in required if k not in doc]
if missing:
return False, f"缺必填字段: {missing}"
if not doc["responses"]:
return False, "responses为空"
if not doc["summary"]:
return False, "缺少功能描述"
return True, "文档完整"
def error_code_table(method):
base = {200: "成功", 400: "参数错误", 404: "资源不存在", 500: "服务端错误"}
if method == "POST":
base[201] = "创建成功"
return base
硬性规则
- 非法HTTP方法直接抛错（validate 拒绝）
- 未提供参数标 required=False，不编造参数类型
- 错误码仅通用HTTP语义，不虚构业务码
示例
parse_endpoint("/api/clients", "post", "新增客户", {"name": {"required": True}})
→ doc.operationId 含 _post，parameters含name(required=True)；validate_doc=True；error_code_table含201
