Add header matching to API groups

[jacob-swanson]

Is your feature request related to a problem? Please describe.
I am using an HTTP header for versioning my API. I want to create separate groups for each version of the API that I support.

Describe the solution you'd like
In addition to packages and paths, I would like to specify header values as well when creating an API group.

Something like this:

@Bean
public GroupedOpenApi v1Api() {
       Map<String,List<String>> headers = Map.of(
           "X-Api-Version", List.of("1.*")
       );
	return GroupedOpenApi.builder().setGroup("stores").headersToMatch(headers)
			.build();
}

Describe alternatives you've considered
None so far

Additional context
None

[KuliginStepan]

@jacob-swanson header versioning may be difficult with swagger, because if you have 2 endpoints with the same path, but different versions, swagger will render only one of them

[jacob-swanson]

I see. I thought it might build the endpoint information after matching to the group. But as I understand it now, that information is built first, then it's filtered into groups.

After looking into it more, URL versioning is going to be fairly straight forward. I've now built a working solution for it. One thing that would make it much easier would be if the GroupedOpenApi constructor wasn't private.

Right now I'm making classes like this for each version:

@Configuration
public class ApiGroupV20200222 extends ApiGroupDefinition {
    public static final String V20200222 = "2020-02-22";

    public ApiGroupV20200222(List<OpenApiCustomiser> customisers) {
        super(customisers);
    }

    @Override
    public String getVersionString() {
        return V20200222;
    }

    @Bean("groupedOpenApi20200222")
    @Override
    public GroupedOpenApi groupedOpenApiBean() {
        return startGroupBuilder().build();
    }
}

It would be a easier if I could have my ApiGroupDefinition class extend GroupedOpenApi. I could remove the @Bean method then.

[bnasslahsen]

@jacob-swanson,

GroupedOpenApi constructor is private, to to incite people to use spring Beans to initialize the GroupedOpenApi classes. (This is very important in group definitions)

If you need to filter using header matching.
You can define your own OpenApiCustomiser and then pass it to GroupedOpenApi Bean.
For example:

@Bean
public GroupedOpenApi groupOpenApi() {
	return GroupedOpenApi.builder()
			.setGroup("v1").packagesToScan("test.org.springdoc.api")
			.addOpenApiCustomiser(new HeaderFilter("X-API-VERSION", "1"))
			.build();
}
public class HeaderFilter implements OpenApiCustomiser {

	private final String headerName;

	private final String HeaderValue;

	public HeaderFilter(String headerName, String HeaderValue) {
		this.headerName = headerName;
		this.HeaderValue = HeaderValue;
	}

	@Override
	public void customise(OpenAPI openApi) {
		openApi.getPaths().entrySet().removeIf(path -> path.getValue().readOperations().stream()
		.anyMatch(operation -> operation.getParameters() == null 
			|| operation.getParameters().stream().noneMatch(
			parameter -> ParameterIn.HEADER.toString().equals(parameter.getIn())
					&& parameter.getName().equals(headerName)
					&& parameter.getSchema().getEnum().contains(HeaderValue)
		)));
	}
}

[paolopiccinini]

@bnasslahsen

openApi.getPaths().entrySet().removeIf(
                path -> path.getValue().readOperations().stream()
                .anyMatch(
                        operation -> operation.getParameters() == null
                        || operation.getParameters().stream().noneMatch(
                        parameter -> ParameterIn.HEADER.toString().equals(parameter.getIn())
                                && parameter.getName().equals(headerName)
                                && parameter.getSchema().getEnum().contains(HeaderValue)
                )));

will exclude all paths operation.getParameters() is retrivign the quey param and not the headers.The list is always null fi there is no query param.. How to filter on the headers of the operation I don't see any method to get the headers.