Springfox documentation - global headers in separate chapter

Question

I'm working in a project where we are using springfox with maven to generate API documentation if form of PDF. We have 'common headers' which are added to all of the requests. I'm using .globalOperationParameters() to add them to documentation but for our purposes the way it's displayed is unsatisfactory. Headers are added to each request and they are unnecessary duplicated. Instead i would prefer to have one chapter called "common headers" and not include them in requests. Is this even possible? Maybe i can add this chapter in form of static file?

Answer 1

I've found solution, maybe someone will be interested in it. Here it is, in swagger dock configuration i've added global parameter called common headers like this:

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());
}

brackets << >> in description will allow creating a link in output pdf document to common headers section. Unfortunately be aware that this solution creates error in swagger.json file because of usage of such a brackets.

Then i'm using swagger2markup to generate ASCII docs out of swagger.json file. Those files are stored e.g in folder asciiDocs. To the same folder i'm copying my own, write by hand ASCII document with common headers i'm using in my REST API. The important thing is to add line:

[[_commonHeaders]]

to link this doc with common headers global parameter description.

Then with usage of Ascii doctor i'm generating output PDF file with inseted into my own ASCII doc.

And that's it:

enter image description here

enter image description here