Support for content-type negotiation?

[SledgeHammer01]

Hi,

I am migrating from Springfox. My rest api uses content-type negotiation for version control. So I have a "V1" docket and a "V2" docket for example. I understand how to migrate that.

In Springfox, I would implement content-type negotation as follows:

@Operation(summary="Conducts a test.")
@ApiResponses(value={
	@ApiResponse(responseCode="200", description="OK")
})
@RequestMapping(path={ "", "v1" }, method=RequestMethod.GET, produces={ "application/vnd.xxx.yyy.v1+json" })
public String test() {
	return "{ \"version\": \"v1\" }";
}

@Operation(summary="Conducts a test.")
@ApiResponses(value={
	@ApiResponse(responseCode="200", description="OK")
})
@RequestMapping(path={ "", "v2" }, method=RequestMethod.GET, produces={ "application/vnd.xxx.yyy.v2+json", "application/json" })
public CustomerDto testV2() {
	return new CustomerDto();
}

Step 1: Note that test() maps to "" and "\v1" while testV2() ALSO maps to "", but "\v2" instead. Also note that test() carries a vnd...v1 content-type while testV2() carries a vnd...v2 content-type.
Step 2: swagger configuration would create a V1 docket and a V2 docket and using the path filter would HIDE anything that matches a regex pattern of \.v\d+\+.

Issue 1: Springdoc takes a String[] of paths while Springfox supported a predicate... that's fine, I can dynamically build a String[] and filter out the versioned paths, but it would be nice to have the predicate filter :D.

Issue 2: I'm not sure of a work-around for this part... so, lets assume I do the work around for Issue #1, this would result in me "theoretically" getting:

route=/, handler=test()
route=/, handler=testV2()

That won't work with content-type negotiation as there is no way for me to filter that out by path since they both map to the same path.

The way Springfox supported this was through docket.select().apis(...) which is also a predicate, but it let you filter out methods based on something other then route. In Springfox's case, the api filter passes in a springfox.documentation.RequestHandler which is basically a method wrapper.

This allowed me to use reflection to get the method annotations, I would specifically pull the @RequestMapping annotation and apply some fallback logic, but in general:

docket "v1" -> api filter -> include the "vnd.xxx.yyy.v1+json" method, exclude others
docket "v2" -> api filter -> include the "vnd.xxx.yyy.v2+json" method, exclude others

This method of version control is gaining traction, would be very nice to be able to migrate to Springdoc if you can implement some technique for handling this :D.

[bnasslahsen]

Hi @SledgeHammer01,

You can define your own OpenApiCustomiser, where you have full control of the OpenAPI definition Bean.

Here is a sample code, that can help you achieve what you are describing. Let us know if it solves your problem.

import io.swagger.v3.core.filter.SpecFilter;
import io.swagger.v3.oas.models.OpenAPI;
import org.springdoc.core.customizers.OpenApiCustomiser;

public class ContentTypeFilter extends SpecFilter implements OpenApiCustomiser {

    private final String contentType;

    public ContentTypeFilter(String contentType) {
        this.contentType = contentType;
    }

    @Override
    public void customise(OpenAPI openApi) {
        openApi.getPaths().entrySet().removeIf(path -> path.getValue().readOperations().stream()
                .anyMatch(operation -> operation.getResponses().values().stream().noneMatch(apiResponse -> apiResponse.getContent()
                        .containsKey(this.contentType))));
        super.removeBrokenReferenceDefinitions(openApi);
    }
}

And then your GroupedOpenApi Bean:

@Bean
public GroupedOpenApi groupOpenApi() {
	return GroupedOpenApi.builder()
		.setGroup("v1 group").packagesToScan("test.org.springdoc.api")
		.addOpenApiCustomiser(new ContentTypeFilter("application/vnd.xxx.yyy.v1+json"))
		.build();
}