swagger-api / swagger-api/swagger-ui

Markdown export missing parameter descriptions

Open
#10,947 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the issue through Swagger-UI's “Copy as Markdown” entry point with an OpenAPI 3.0 operation whose parameters have descriptions. Trace the Markdown export path and compare its parameter table with the rendered Request Parameters. Done means the exported Description column preserves each parameter's description, and the reproduction is covered by a regression test.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.