## 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 导入流程(无需任何配置变更)