API-Platform Swagger UI参数描述混入输入框占位符问题求助

问题核心：Swagger UI默认会把参数的description内容直接作为输入框的占位符，导致HTML/Markdown标签直接显示在输入框里，造成格式混乱。

以下是两种可行的解决方式：

方式1：使用扩展字段区分描述与占位符 #

OpenAPI规范支持自定义扩展字段（前缀x-），我们可以添加x-placeholder来定义输入框的简洁占位符，把详细描述保留在description中。

第一步：修改参数定义代码 #

在参数配置里添加x-placeholder字段，示例如下：

new Parameter(
    name: 'siren', 
    description: "<p>Recherche par <code>siren</code>.</p>",
    schema: ['type' => 'string'], 
    in: 'query', 
    required: false,
    'x-placeholder' => 'Siren'
), 
new Parameter(
    name: 'raison_sociale_deduite', 
    description: "Recherche par `raison sociale deduite`",
    schema: ['type' => 'string'], 
    in: 'query', 
    required: false,
    'x-placeholder' => 'Raison sociale déduite'
)

第二步：配置Swagger UI识别扩展字段 #

在Swagger UI的初始化代码中，添加插件逻辑，将x-placeholder的值设置为输入框的占位符，覆盖默认行为：

const ui = SwaggerUIBundle({
  url: "你的OpenAPI规范文件路径",
  dom_id: '#swagger-ui',
  // 其他原有配置...
  plugins: [
    {
      statePlugins: {
        spec: {
          wrapActions: {
            updateSpec: (originalAction) => (spec) => {
              // 遍历所有参数，处理x-placeholder
              const handleParameters = (params) => {
                if (!params) return;
                params.forEach(param => {
                  if (param['x-placeholder']) {
                    param.placeholder = param['x-placeholder'];
                  }
                });
              };

              // 处理路径中的接口参数
              Object.values(spec.paths || {}).forEach(pathItem => {
                Object.values(pathItem).forEach(operation => {
                  handleParameters(operation.parameters);
                });
              });

              // 处理全局参数
              handleParameters(spec.parameters);

              return originalAction(spec);
            }
          }
        }
      }
    }
  ]
});

方式2：直接修改Swagger UI的默认占位符逻辑 #

如果不想添加扩展字段，可以直接自定义Swagger UI的行为，让输入框占位符只显示参数名，忽略description内容。在Swagger UI初始化时添加如下配置：

const ui = SwaggerUIBundle({
  url: "你的OpenAPI规范文件路径",
  dom_id: '#swagger-ui',
  // 其他原有配置...
  onComplete: () => {
    // 遍历所有输入框，替换占位符为参数名
    document.querySelectorAll('.parameter input').forEach(input => {
      const paramName = input.closest('.parameter').querySelector('.parameter__name').textContent.trim();
      input.placeholder = paramName;
    });
  }
});

注：这种方式依赖Swagger UI的DOM结构，若版本更新可能需要调整选择器。

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