# 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 调用

