[FIXED] Understand and configure Spring JSON marshalling configuration of String responses

Issue

For a Spring MVC project (not Spring Boot) I'm configuring the JSON converter to customise JSON responses of all REST endpoints i.e. removing null fields and setting a date format. After introducing SpringDoc to the project I've had to add a StringHttpMessageConverter to prevent the generated OpenAPI JSON from being returned as a string.

Without the StringHttpMessageConverter the OpenAPI JSON looks like this:

"{\"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\"}}}}}}"

With the StringHttpMessageConverter it looks like this, which is the desired result:

{"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"}}}}}}

This does however cause problems with several endpoints that return a string as their response. They should return a valid JSON string: "response-string" but instead they return the string as plain text: response-string, omitting the double quotes, making it invalid JSON.

How can I keep the current configuration intact so the SpringDoc OpenAPI JSON is returned correctly while also having endpoints that have a string response return a valid JSON string?

Configuration used:

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    WebContentInterceptor webContentInterceptor = new WebContentInterceptor();
    webContentInterceptor.setCacheSeconds(0);
    webContentInterceptor.setUseExpiresHeader(true);
    webContentInterceptor.setUseCacheControlHeader(true);
    webContentInterceptor.setUseCacheControlNoStore(true);
    registry.addInterceptor(webContentInterceptor);
  }

  @Override
  public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
    Map<String, MediaType> mediaTypes = new HashMap<>();
    mediaTypes.put("json", MediaType.APPLICATION_JSON);
    mediaTypes.put("xml", MediaType.APPLICATION_XML);

    configurer.favorPathExtension(false);
    configurer.favorParameter(true);
    configurer.mediaTypes(mediaTypes);
    configurer.defaultContentType(MediaType.APPLICATION_JSON_UTF8);
  }

  @Override
  public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
    configurer.enable();
  }

  @Override
  public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    // Note that the order matters here! If the StringHttpMessageConverter is add after the jsonConverter
    // the documentation JSON is returned as a giant string instead of a (valid) JSON object
    converters.add(new StringHttpMessageConverter());
    converters.add(jsonConverter());
  }

  @Bean
  public MappingJackson2HttpMessageConverter jsonConverter() {
    List<MediaType> supportedMediaTypes = new ArrayList<>();
    supportedMediaTypes.add(MediaType.APPLICATION_JSON);

    Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder();
    builder.serializationInclusion(JsonInclude.Include.NON_NULL);
    builder.timeZone(TimeZone.getTimeZone(timeZone));

    MappingJackson2HttpMessageConverter jsonConverter = new MappingJackson2HttpMessageConverter(
        builder.build()
    );
    jsonConverter.setSupportedMediaTypes(supportedMediaTypes);
    return jsonConverter;
  }

  @Bean
  public Jaxb2Marshaller jaxb2Marshaller() {
    Jaxb2Marshaller jaxb2Marshaller = new Jaxb2Marshaller();
    jaxb2Marshaller.setClassesToBeBound(KioskProfiel.class, KioskProfielRegel.class, TitlesetTO.class, TitlesetTitel.class);

    return jaxb2Marshaller;
  }

  @Bean
  public MarshallingHttpMessageConverter marshallingConverter() {
    List<MediaType> supportedMediaTypes = new ArrayList<>();
    supportedMediaTypes.add(MediaType.APPLICATION_XML);

    MarshallingHttpMessageConverter marshallingConverter = new MarshallingHttpMessageConverter(jaxb2Marshaller());
    marshallingConverter.setSupportedMediaTypes(supportedMediaTypes);
    return marshallingConverter;
  }
}

Edit

I've tried overriding the OpenApiResource setting the produces value of the endpoint to TEXT_PLAIN_VALUE and too application/json but the problem still persists. Attempting to change the return type from String to TextNode isn't allowed so that doesn't seem to be an option. Alternatively I've tried to resolve the problem by registering a Filter to correct the malformed response but that to doesn't work.

Maybe I'm still missing something but I'm out of options. With my current project configuration I can't get SpringDoc to return valid OpenAPI JSON when using a custom MappingJackson2HttpMessageConverter. For now I'll stick to Swagger 2.0 and will look into an alternative library to move to OpenAPI 3.0.

Solution

A working solution has finally been found! It consists of two parts. The first is configuring the converters. In short we register the default converts after which the default JSON converter, MappingJackson2HttpMessageConverter is removed and our custom JSON converter is added as the first converter to the list of converters. It is important that the custom JSON converter is in the list of converters before the StringHttpMessageConverter else endpoints that return JSON that have a String as their Java return type return the string without double quotes making it invalid JSON.

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

  @Override
  public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
    converters.removeIf(converter -> converter instanceof MappingJackson2HttpMessageConverter);
    converters.add(0, jsonConverter());
  }

  @Bean
  public MappingJackson2HttpMessageConverter jsonConverter() {
    List<MediaType> supportedMediaTypes = new ArrayList<>();
    supportedMediaTypes.add(MediaType.APPLICATION_JSON);

    Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder();
    builder.serializationInclusion(JsonInclude.Include.NON_NULL);
    builder.timeZone(TimeZone.getTimeZone(timeZone));

    MappingJackson2HttpMessageConverter jsonConverter = new MappingJackson2HttpMessageConverter(
        builder.build()
    );
    jsonConverter.setSupportedMediaTypes(supportedMediaTypes);
    return jsonConverter;
  }

}

Secondly, this causes the OpenAPI JSON to be one big (escaped) string, as mentioned in the question. To resolve this problem we override the openapiJson method (and endpoint) from the OpenApiWebMvcResource class, which is used by default to return the OpenAPI JSON, to produce text/plain instead of application/json. This way the documentation JSON isn't returned as an (escaped) string anymore.

@RestController
public class OpenApiResource extends OpenApiWebMvcResource {

  @Override
  @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);
  }

}

Note that for brevity only the relevant methods are listed in both example classes above.

Answered By - Pieter
Answer Checked By - Mildred Charles (JavaFixing Admin)