如何实现Swagger文档隐藏参数但保留OpenAPI Java客户端生成该参数？

要实现「参数不在Swagger UI显示但保留在Java客户端方法签名中」的需求，不能用hidden=true——因为这个注解会直接将参数从OpenAPI规范（Spec）中移除，导致客户端生成工具也无法识别它。正确的思路是让参数保留在Spec里，仅在Swagger UI层面隐藏它，以下是两种可行方案：

方案1：自定义Swagger UI的参数过滤逻辑 #

通过修改Swagger UI的初始化脚本，在加载完成后过滤掉指定参数，而原始的OpenAPI接口文档（如/v3/api-docs）仍会保留该参数，确保客户端生成工具能读取到。

以SpringDoc集成的Swagger UI为例，修改swagger-ui/index.html中的初始化代码：

<script>
window.onload = function() {
  const ui = SwaggerUIBundle({
    url: "/v3/api-docs",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [SwaggerUIBundle.plugins.DownloadUrl],
    onComplete: function() {
      // 遍历所有API路径和方法，过滤目标参数
      const paths = ui.spec.paths;
      Object.keys(paths).forEach(pathKey => {
        const path = paths[pathKey];
        Object.keys(path).forEach(method => {
          const operation = path[method];
          if (operation.parameters) {
            // 过滤掉header中名为X-Custom-Parameter的参数
            operation.parameters = operation.parameters.filter(param => 
              !(param.in === 'header' && param.name === 'X-Custom-Parameter')
            );
          }
        });
      });
      // 更新UI显示
      ui.updateSpec(ui.spec);
    }
  });
  window.ui = ui;
};
</script>

方案2：用自定义OpenAPI扩展标记参数 #

给目标参数添加自定义扩展，让Swagger UI识别并隐藏它，同时参数仍会保留在OpenAPI Spec中。

步骤1：在Java代码中添加扩展注解 #

@Parameter(
    name = "X-Custom-Parameter", 
    in = ParameterIn.HEADER,
    extensions = @Extension(
        name = "x-swagger-ui-hidden", 
        properties = @ExtensionProperty(name = "value", value = "true")
    )
)

步骤2：修改Swagger UI的渲染逻辑 #

在Swagger UI的代码中，添加对x-swagger-ui-hidden扩展的识别，当参数带有该扩展且值为true时，不渲染该参数。例如在参数渲染前添加过滤逻辑：

function shouldRenderParameter(param) {
  return !param['x-swagger-ui-hidden'];
}

这种方式更灵活，可针对单个参数精准控制是否在UI中显示。

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