huang
45aa7deb87
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m33s
主要改动： - 新增交互式环境配置脚本 (scripts/setup-env.sh) - 新增本地启动快捷脚本 (scripts/run-local.sh) - 新增环境变量模板文件 (.env.example) - 部署模式改版：使用嵌入式配置 + 环境变量覆盖 - 添加对象存储功能支持 - 改进 IoT 卡片导入任务 - 优化 OpenAPI 文档生成 - 删除旧的配置文件，改用嵌入式默认配置
1.8 KiB
1.8 KiB
Why
当前项目的 OpenAPI 文档生成模块只支持通过 RouteSpec.Summary 设置接口的简短摘要，无法添加详细的 Markdown 格式说明。前端团队使用 Apifox 查看 API 文档时，需要在某些接口上看到更详细的使用说明、注意事项、业务规则等信息。
OpenAPI 规范的 Operation 对象支持 description 字段，且该字段明确支持 CommonMark Markdown 语法。Apifox 作为 OpenAPI 工具，能够正确渲染这些 Markdown 内容。因此需要扩展当前的文档生成模块以支持此功能。
What Changes
- 在
RouteSpec结构体中新增Description字段，用于设置接口的详细 Markdown 说明 - 修改
pkg/openapi/generator.go中的AddOperation和AddMultipartOperation方法，将 Description 写入 OpenAPI 规范 - 更新
internal/routes/registry.go中的Register函数以传递 Description 参数 - 更新 API 文档规范，说明 Description 字段的使用方法和 Markdown 语法支持
Capabilities
New Capabilities
openapi-markdown-description: 支持在 OpenAPI 接口文档中添加 Markdown 格式的详细描述，包括表格、列表、代码块等富文本内容
Modified Capabilities
Impact
受影响的代码:
internal/routes/registry.go- RouteSpec 结构体定义和 Register 函数pkg/openapi/generator.go- AddOperation 和 AddMultipartOperation 方法
受影响的文档:
docs/api-documentation-guide.md- 需要补充 Description 字段使用说明
不受影响:
- 所有现有路由注册代码（Description 字段为可选，空值时行为与当前一致）
- 生成的 OpenAPI 文件格式（符合 OpenAPI 3.0.3 规范）
- Apifox 导入流程（无需任何配置变更）