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 文档生成 - 删除旧的配置文件，改用嵌入式默认配置
37 lines
1.8 KiB
Markdown
37 lines
1.8 KiB
Markdown
## 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 导入流程（无需任何配置变更）
|