Malformed api-docs JSON when custom HttpMessageConverter is used

[peter-szepe-geneea]

When custom HttpMessageConverter is used malformed api-docs endpoint produces malformed JSON

Steps to reproduce the behavior:

• spring-boot version 2.2.6.RELEASE
• springdoc-openapi 1.3.5-SNAPSHOT
• the actual result is a JSON String created from the String produced by org.springdoc.webmvc.api.OpenApiResource#openapiJson. The original response is wrapped with a leading and trailing double quote and all the double internal double quotes are escaped:
  "{\"openapi\":\"3.0.1\",\"info\":{\"title\":\"OpenAPI definition\",\"version\":\"v0\"},\"servers\":[{\"url\":\"http://localhost:8080\",\"description\":\"Generated server url\"}],\"paths\":{\"/get\":{\"get\":{\"tags\":[\"controller\"],\"operationId\":\"getSomeMap\",\"responses\":{\"200\":{\"description\":\"default response\",\"content\":{\"*/*\":{\"schema\":{\"$ref\":\"#/components/schemas/ImmutableMultimapStringString\"}}}}}}}},\"components\":{\"schemas\":{\"ImmutableMultimapStringString\":{\"type\":\"object\",\"properties\":{\"empty\":{\"type\":\"boolean\"}}}}}}"
• a sample application can be found in https://github.com/Geneea/springdoc-test

Expected behavior

• I would expect that org.springdoc.webmvc.api.OpenApiResource#openapiJson should not do the conversion from OpenAPI to String. Just return OpenAPI or ResponseEntity<OpenAPI> and leave the serialization for the registered HttpMessageConverter.

Additional context
An ugly fix for this problem is https://github.com/Geneea/springdoc-test/blob/master/src/main/java/com/geneea/springdoc/FixApiDocsWithFilter.java
registering a Filter what corrects the malformed response.

Same problem is described in https://stackoverflow.com/questions/59393191/endpoint-api-docs-doesnt-work-with-custom-gsonhttpmessageconverter

[bnasslahsen]

@peter-szepe-geneea,

Only one @Configuration class may have the @EnableWebMvc annotation to import the Spring Web MVC configuration.

If you can remove @EnableWebMvc from your sample, it will work directly.
If you can not, because you changing the default list of Http Converters with our own, you should override OpenApiResource as follow:

@Component
public class OpenApiResource extends org.springdoc.webmvc.api.OpenApiResource {

	public OpenApiResource(OpenAPIBuilder openAPIBuilder, AbstractRequestBuilder requestBuilder, GenericResponseBuilder responseBuilder, OperationBuilder operationParser, RequestMappingInfoHandlerMapping requestMappingHandlerMapping, Optional<ActuatorProvider> servletContextProvider, Optional<List<OpenApiCustomiser>> openApiCustomisers, SpringDocConfigProperties springDocConfigProperties, Optional<SecurityOAuth2Provider> springSecurityOAuth2Provider) {
		super(openAPIBuilder, requestBuilder, responseBuilder, operationParser, requestMappingHandlerMapping, servletContextProvider, openApiCustomisers, springDocConfigProperties, springSecurityOAuth2Provider);
	}

	@Operation(hidden = true)
	@GetMapping(value = API_DOCS_URL, produces = MediaType.TEXT_PLAIN_VALUE)
	public String openapiJson(HttpServletRequest request, @Value(API_DOCS_URL) String apiDocsUrl)
			throws JsonProcessingException {
		calculateServerUrl(request, apiDocsUrl);
		OpenAPI openAPI = this.getOpenApi();
		return Json.mapper().writeValueAsString(openAPI);
	}

	private void calculateServerUrl(HttpServletRequest request, String apiDocsUrl) {
		String requestUrl = decode(request.getRequestURL().toString());
		String calculatedUrl = requestUrl.substring(0, requestUrl.length() - apiDocsUrl.length());
		openAPIBuilder.setServerBaseUrl(calculatedUrl);
	}
}

OpenApiResource, will return TEXT_PLAIN_VALUE starting from the next release v1.3.5, so you won't need to override it for this use case.

[Aloren]

@bnasslahsen The fix provided in ee08333 is breaking all our automated tests for Swagger endpoints in all services. Is it possible to leave content-type to be json as it was previously, but instead of returning raw string-- return some dto, so that spring does all json conversion?

[bnasslahsen]

Hi @Aloren,

Changing the return type to DTO, is not easy. It require a custom serializer, which is already provided by swagger-core.
Also if your tests are based on the payload, Changing to DTO may change the result if we don't use the same serializer.
Can't you just adapt your failing tests by adapring the content-type ?

[Aloren]

We can of course add additional workarounds for our tests, but the main issue is that such response format violates HTTP specs. With such change content negotiation is completely broken and whoever knows what functionality it might break in the future. This is a type of fix that gives short-term benefits, but may lead to interesting new issues :)

[bnasslahsen]

I would say that the impact should be limited because the return type was already of type String.
But i agree its better to return it as object.
Hopefully, If i have some time, i will have a look at it.

[bnasslahsen]

@Aloren,

This change is reverted back, as it seems more going to cause problems than resolving them.

@peter-szepe-geneea,

You can override the OpenApiResource as proposed earlier. This seems the less harmful solution

[bnasslahsen]

its now available on v1.3.7.

[MikeMitterer]

@bnasslahsen I'm using 1.3.9 but I have still the same problem???
openapi_version=1.3.9+ gson_version=2.8.6

    implementation("org.springdoc:springdoc-openapi-webmvc-ui:${openapi_version}")
    implementation("org.springdoc:springdoc-openapi-webmvc-core:${openapi_version}")
    implementation("org.springdoc:springdoc-openapi-security:${openapi_version}")
    implementation("org.springdoc:springdoc-openapi-kotlin:${openapi_version}")

    implementation("com.google.code.gson:gson:$gson_version")

With SpringFox I can register an Adapter: springfox/springfox#2758...

[bnasslahsen]

@MikeMitterer,

springdoc-openapi is built on top of swagger-core, which is based on jackson;
There is already existing request to add support for GSON, but not sure it will be added in short term:

• Add GSON support swagger-api/swagger-core#1826

As described before, you can override the OpenApiResource as follow:

@Component
public class OpenApiResource extends org.springdoc.webmvc.api.OpenApiResource {

	public OpenApiResource(OpenAPIBuilder openAPIBuilder, AbstractRequestBuilder requestBuilder, GenericResponseBuilder responseBuilder, OperationBuilder operationParser, RequestMappingInfoHandlerMapping requestMappingHandlerMapping, Optional<ActuatorProvider> servletContextProvider, Optional<List<OperationCustomizer>> operationCustomizers, Optional<List<OpenApiCustomiser>> openApiCustomisers, SpringDocConfigProperties springDocConfigProperties, Optional<SecurityOAuth2Provider> springSecurityOAuth2Provider, Optional<RouterFunctionProvider> routerFunctionProvider) {
		super(openAPIBuilder, requestBuilder, responseBuilder, operationParser, requestMappingHandlerMapping, servletContextProvider, operationCustomizers, openApiCustomisers, springDocConfigProperties, springSecurityOAuth2Provider, routerFunctionProvider);
	}

	@Operation(hidden = true)
	@GetMapping(value = Constants.API_DOCS_URL, produces = MediaType.TEXT_PLAIN_VALUE)
	public String openapiJson(HttpServletRequest request, @Value(Constants.API_DOCS_URL) String apiDocsUrl)
			throws JsonProcessingException {
		calculateServerUrl(request, apiDocsUrl);
		OpenAPI openAPI = this.getOpenApi();
		return Json.mapper().writeValueAsString(openAPI);
	}
}