Skip to content

For SpringDoc OpenAPI 1.6, Swagger UI unable to render definition #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
alan-czajkowski opened this issue Apr 29, 2023 · 7 comments
Closed
Labels
documentation Improvements or additions to documentation duplicate This issue or pull request already exists

Comments

@alan-czajkowski
Copy link

alan-czajkowski commented Apr 29, 2023

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)

@alan-czajkowski alan-czajkowski changed the title Swagger UI unable to render definition For SpringDoc OpenAPI 1.6, Swagger UI unable to render definition Apr 30, 2023
@uc4w6c
Copy link
Contributor

uc4w6c commented Apr 30, 2023

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

@alan-czajkowski
Copy link
Author

@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
Copy link
Contributor

uc4w6c commented May 1, 2023

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

@alan-czajkowski
Copy link
Author

alan-czajkowski commented May 1, 2023

@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
Copy link
Contributor

bnasslahsen commented May 1, 2023

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

@bnasslahsen bnasslahsen added the duplicate This issue or pull request already exists label May 1, 2023
@alan-czajkowski
Copy link
Author

alan-czajkowski commented May 1, 2023

@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 bnasslahsen added invalid This doesn't seem right documentation Improvements or additions to documentation and removed invalid This doesn't seem right labels May 1, 2023
@bnasslahsen bnasslahsen transferred this issue from springdoc/springdoc-openapi May 1, 2023
@bnasslahsen
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation duplicate This issue or pull request already exists
Projects
None yet
Development

No branches or pull requests

3 participants