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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions