For SpringDoc OpenAPI 1.6, Swagger UI unable to render definition

[alan-czajkowski]

Describe the bug

Swagger UI page complains about rendering the definition, shows error on page saying: http://localhost:8080/swagger-ui/index.html

Unable to render this definition
The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

when running the Spring Boot Maven plugin:

$ mvn clean spring-boot:run

To Reproduce

Steps to reproduce the behavior:

• What version of spring-boot you are using?

Using Spring Boot 2.6:

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.6.14</version>
    <!-- # lookup parent from repository -->
    <relativePath />
  </parent>

• What modules and versions of springdoc-openapi are you using?

Using SpringDoc 1.6:

    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.6.15</version>
    </dependency>
    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-security</artifactId>
      <version>1.6.15</version>
    </dependency>

• How are you running the application?

Run using the Spring Boot Maven plugin:

$ mvn clean spring-boot:run

Expected behavior

Swagger UI does not throw error

Additional context

Config:

springdoc:
  writer-with-default-pretty-printer: true
  api-docs:
    enabled: true
    version: "openapi_3_0"
  swagger-ui:
    enabled: true
    operations-sorter: "method"
    tags-sorter: "alpha"
    display-request-duration: true

Using custom HTTP message converters:

  @Override
  public void configureMessageConverters(List<HttpMessageConverter<?>> messageConverters) {
    messageConverters.add(new StringHttpMessageConverter());
    messageConverters.add(new MappingJackson2HttpMessageConverter(JsonUtils.createObjectMapper()));
  }

Unable to see JSON spec at: http://localhost:8080/v3/api-docs only shows some kind of Base64 output (not JSON)

[uc4w6c]

It looks like swagger ui doesn't support 3.1.0 version yet. see: https://github.com/swagger-api/swagger-ui/issues/5891

[alan-czajkowski]

@uc4w6c OpenAPI 3.1 is not the problem, I have updated the issue description with a 3.0 reference that still produces the same problem:

springdoc:
  api-docs:
    version: "openapi_3_0"

[uc4w6c]

@alan-czajkowski I see. Please see. springdoc/springdoc-openapi#2143

[alan-czajkowski]

@uc4w6c according to that issue you posted https://github.com/springdoc/springdoc-openapi/issues/2143 the fix ends up being adding the ByteArrayHttpMessageConverter to the list of converters:

  @Override
  public void configureMessageConverters(List<HttpMessageConverter<?>> messageConverters) {
    messageConverters.add(new StringHttpMessageConverter());
    messageConverters.add(new ByteArrayHttpMessageConverter());
    messageConverters.add(new MappingJackson2HttpMessageConverter(JsonUtils.createObjectMapper()));
  }

but this is hardly a proper fix, this is just a work-around, I hope the issue I described gets properly resolved

[bnasslahsen]

@alan-czajkowski,

You are overriding the default spring registered HttpMessageConverter, you should have ByteArrayHttpMessageConverter registered as well to have proper springdoc-openapi support.

This is the required setting for your use case.

Are you having any other fix in mind, that we didn't integrate in the library ?

[alan-czajkowski]

@bnasslahsen this is becoming a notorious use-case, and the SpringDoc documentation does not properly describe this use-case, that is becoming very popular and frustrating to users (who read the documentation)

[bnasslahsen]

This section is added in the FAQ, for this use-case:

• https://springdoc.org/#why-am-i-getting-an-error-swagger-ui-unable-to-render-definition-when-overriding-the-default-spring-registered-httpmessageconverter