Springfox 文档 - 单独章节中的全局标题答案

【问题标题】：Springfox documentation - global headers in separate chapterSpringfox 文档 - 单独章节中的全局标题
【发布时间】：2021-02-02 06:56:33
【问题描述】：

我正在一个项目中工作，我们使用 springfox 和 maven 来生成 PDF 格式的 API 文档。我们有添加到所有请求中的“通用标头”。我正在使用.globalOperationParameters() 将它们添加到文档中，但出于我们的目的，它的显示方式并不令人满意。标头被添加到每个请求中，并且它们是不必要的重复。相反，我希望有一章称为“通用标题”，而不是将它们包含在请求中。这甚至可能吗？也许我可以以静态文件的形式添加这一章？

【问题讨论】：

标签： java maven swagger springfox

【解决方案1】：

我找到了解决方案，也许有人会对它感兴趣。就是这样，在 swagger dock 配置中，我添加了名为 common headers 的全局参数，如下所示：

In dock:
                .globalOperationParameters(commonHeaders())

and:
    private List<Parameter> commonHeaders(){
    return Arrays.asList(new ParameterBuilder()
            .name("Common headers")
            .description("Headers described in common headers chapter - <<_commonHeaders, Common Headers>>")
            .modelRef(new ModelRef("String"))
            .parameterType("header")
            .required(true)
            .build());
}

括号 > 在描述中将允许在输出 pdf 文档中创建到公共标题部分的链接。不幸的是，请注意，由于使用了这样的括号，此解决方案会在 swagger.json 文件中产生错误。

然后我使用swagger2markup 从 swagger.json 文件中生成 ASCII 文档。这些文件存储在例如文件夹 asciiDocs 中。到我自己复制的同一个文件夹中，用我在我的 REST API 中使用的通用标题手动编写 ASCII 文档。重要的是添加行：

[[_commonHeaders]]

将此文档与通用标题全局参数描述链接。

然后使用Ascii医生生成输出PDF文件，并插入到我自己的ASCII文档中。

就是这样：

enter image description here

【讨论】：