Springfox文档：如何将全局请求头独立为单独章节？

当然可行！你可以通过调整Springfox配置+静态文档注入的方式实现这个需求，既消除接口中的冗余显示，又能把公共请求头统一放在独立章节里。下面是具体的实现步骤：

第一步：移除Springfox中的全局参数重复配置 #

首先，把原来通过.globalOperationParameters()添加公共请求头的代码删掉——这是导致每个接口下都重复显示的根源。

修改你的Docket配置类，去掉类似这样的代码块：

.globalOperationParameters(Arrays.asList(
        new ParameterBuilder()
                .name("Authorization")
                .description("Bearer token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(true)
                .build()
))

第二步：创建静态文档定义公共请求头章节 #

因为你用Maven生成PDF，通常流程是Springfox生成Swagger JSON → 转成Asciidoc → 转成PDF。所以我们可以直接用Asciidoc静态文件来定义公共请求头的内容。

在项目中创建一个Asciidoc文件，比如src/main/asciidoc/common-headers.adoc，内容示例：

== 公共请求头

所有API请求必须携带以下公共请求头：

|===
| 请求头名称 | 数据类型 | 是否必填 | 描述说明

| Authorization
| string
| ✅ 是
| 身份认证令牌，格式为 `Bearer {token}`

| X-Request-Trace-ID
| string
| ✅ 是
| 请求唯一标识，用于链路追踪与问题排查
|===

第三步：在API文档中引入静态章节 #

接下来要让生成的API文档自动包含这个静态章节。如果用swagger2markup插件生成Asciidoc，你可以：

1. 在swagger2markup的配置中指定生成的主文档路径
2. 在主Asciidoc文件（比如index.adoc）的合适位置添加引入语句：

include::{docsDir}/common-headers.adoc[]

（{docsDir}是swagger2markup插件的内置变量，指向生成的文档目录，你也可以用相对路径）

第四步：调整Maven插件配置确保生效 #

最后检查你的Maven插件配置（swagger2markup-maven-plugin + asciidoctor-maven-plugin），确保它们能正确读取到静态Asciidoc文件，并最终把内容合并到PDF中。

这样一来，生成的PDF文档就会有一个独立的「公共请求头」章节，而每个接口下不会再重复显示这些内容，完美解决冗余问题！

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