OpenAPI查询参数description未完整显示为Swagger文本框placeholder问题咨询

问题解答 #

OpenAPI 规范本身没有原生支持为参数输入框单独定义独立的placeholder字段，Swagger UI 默认会复用参数的description字段内容作为输入框的placeholder，这是框架的默认渲染逻辑，目前没有内置的配置项可以单独设置placeholder。

你可以通过以下两种方案解决长文本被截断的问题：

• 方案1：拆分描述内容，适配默认渲染逻辑
  将需要展示在placeholder的短提示写在description字段中，完整的参数说明可以通过OpenAPI规范允许的自定义扩展字段（x-开头的自定义属性，例如x-full-description）存储。如果是自行部署的Swagger UI，可简单修改前端渲染逻辑，将自定义扩展字段的内容渲染为参数详情区域的完整说明，既可以保证placeholder是短文本不会被截断，也不会丢失完整的参数说明信息。
  参考配置示例：

  "parameters": [                 
    {
      "name": "role",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "请输入角色标识",
      "x-full-description": "This is test description to reproduce placeholder not fit to textbox 可放置所有完整参数说明内容"                       
    }]
  

• 方案2：修改Swagger UI的CSS样式，取消截断限制
  如果你不想调整OpenAPI定义的结构，可以直接修改Swagger UI的样式规则，找到控制输入框placeholder显示的CSS选择器，移除text-overflow: ellipsis、overflow: hidden这类截断属性，也可以同时调整输入框的宽度适配长文本。该方案更适合description长度适中的场景，如果description本身过长，还是更推荐使用方案1拆分内容，避免placeholder过长影响界面使用体验。

内容的提问来源于stack exchange，提问作者Salman