springdoc/springdoc.github.io

For SpringDoc OpenAPI 1.6, Swagger UI unable to render definition

alan-czajkowski opened this issue · 7 comments

alan-czajkowski commented

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 commented

It looks like swagger ui doesn't support 3.1.0 version yet.
see: swagger-api/swagger-ui#5891

alan-czajkowski commented

@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"
alan-czajkowski commented

@uc4w6c according to that issue you posted springdoc/springdoc-openapi#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 commented

@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 commented

@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)

  • 👍2