Skip to content

Markdown export missing parameter descriptions #10947

Description

@zhangjianye201702

Q&A (please complete the following information)

  • OS: Windows
  • Browser: Chrome
  • Version: [请填写浏览器版本]
  • Method of installation: npm
  • Swagger-UI version: [请填写 Swagger-UI 版本]
  • Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

Example Swagger/OpenAPI definition:

# 以“查看报告”接口为例,接口参数均已配置 description 字段
# 例如 header 参数 trace_id 配置了 description: 链路追踪 ID(可选,由网关传入)

Swagger-UI configuration options:

SwaggerUI({
  // 使用默认配置,未做特殊定制
})

Describe the bug you're encountering

在使用 Swagger-UI 的“复制文档”功能(Copy 文档为 Markdown)时,复制得到的 Markdown 文件中,参数说明(Description 列)为空,缺失了各参数对应的描述信息。

具体表现为:

  • 在 Swagger-UI 页面上,每个参数(如 user_codeapp_idsessiontrace_id 等)都能正常显示其描述说明。
  • 但通过复制功能导出的 Markdown 文档里,参数表格的 Description 列为空,没有把参数的 description 字段内容带出来。

To reproduce...

Steps to reproduce the behavior:

  1. 打开 Swagger-UI 页面,进入任一接口(例如“查看报告”接口)。
  2. 查看接口的 Request Parameters,确认每个参数都有对应的 description 说明(如 trace_id 显示“链路追踪 ID(可选,由网关传入)”)。
  3. 使用 Swagger-UI 提供的“复制为 Markdown”功能,复制该接口文档。
  4. 将复制得到的 Markdown 粘贴到 .md 文件中查看。
  5. 发现参数表格的 Description 列为空,参数说明丢失。

Expected behavior

复制导出的 Markdown 文档中,参数表格的 Description 列应完整保留每个参数的描述说明,与 Swagger-UI 页面上显示的内容一致。

Screenshots

(建议附上两张截图对比:Swagger-UI 页面上参数说明正常显示;复制得到的 Markdown 中参数说明为空。)

Additional context or thoughts

  • 该问题导致导出的接口文档无法作为有效的交付/沟通文档使用,因为参数含义丢失。
  • 怀疑是 Swagger-UI 在生成 Markdown 时,未正确读取或拼接 parameter 的 description 字段。
  • 期望复制功能能完整保留包括 description 在内的所有参数元信息。
Image

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions