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 文档生成 - 删除旧的配置文件，改用嵌入式默认配置
61 lines
2.3 KiB
Markdown
61 lines
2.3 KiB
Markdown
# openapi-markdown-description Specification
|
||
|
||
## Purpose
|
||
TBD - created by archiving change add-openapi-markdown-description. Update Purpose after archive.
|
||
## Requirements
|
||
### Requirement: RouteSpec 支持 Description 字段
|
||
|
||
RouteSpec 结构体 SHALL 包含 `Description` 字段，类型为 `string`，用于设置接口的详细 Markdown 说明。
|
||
|
||
#### Scenario: Description 字段为空时不影响生成
|
||
|
||
- **WHEN** RouteSpec.Description 为空字符串
|
||
- **THEN** 生成的 OpenAPI 规范中该接口不包含 description 字段
|
||
|
||
#### Scenario: Description 字段有内容时写入 OpenAPI
|
||
|
||
- **WHEN** RouteSpec.Description 包含非空内容
|
||
- **THEN** 生成的 OpenAPI 规范中该接口的 description 字段包含该内容
|
||
|
||
### Requirement: Description 支持 Markdown 语法
|
||
|
||
生成器 SHALL 原样保留 Description 字段的 Markdown 内容，不进行转义或处理，以便 OpenAPI 工具（如 Apifox）正确渲染。
|
||
|
||
#### Scenario: 支持基础 Markdown 格式
|
||
|
||
- **WHEN** Description 包含 Markdown 标题、列表、表格、代码块
|
||
- **THEN** 生成的 OpenAPI YAML 文件中保留完整的 Markdown 格式
|
||
|
||
#### Scenario: 支持多行内容
|
||
|
||
- **WHEN** Description 包含多行文本
|
||
- **THEN** 生成的 OpenAPI YAML 文件使用 YAML 多行字符串格式正确表示
|
||
|
||
### Requirement: AddOperation 方法处理 Description
|
||
|
||
AddOperation 方法 SHALL 接受 description 参数并设置到 openapi3.Operation.Description 字段。
|
||
|
||
#### Scenario: 普通接口设置 Description
|
||
|
||
- **WHEN** 调用 AddOperation 且 description 参数非空
|
||
- **THEN** 生成的 Operation 对象包含 Description 字段
|
||
|
||
### Requirement: AddMultipartOperation 方法处理 Description
|
||
|
||
AddMultipartOperation 方法 SHALL 与 AddOperation 一致，支持 description 参数。
|
||
|
||
#### Scenario: 文件上传接口设置 Description
|
||
|
||
- **WHEN** 调用 AddMultipartOperation 且 description 参数非空
|
||
- **THEN** 生成的 multipart/form-data 接口包含 Description 字段
|
||
|
||
### Requirement: Register 函数传递 Description
|
||
|
||
Register 函数 SHALL 从 RouteSpec 中提取 Description 字段并传递给文档生成器。
|
||
|
||
#### Scenario: Register 调用时传递 Description
|
||
|
||
- **WHEN** 调用 Register 函数注册路由
|
||
- **THEN** RouteSpec.Description 被传递到对应的 AddOperation 或 AddMultipartOperation 调用
|
||
|