8

I have installed swagger-ui using the following artifacts in my Java project's pom file:

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

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

I can view the swagger ui for my RESTful endpoints when I go to this URL

http://localhost:8081/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config

but not this link

http://localhost:8081/swagger-ui/index.html

Why is this? How can I change it back to the expected URL?

Dave
  • 185
  • 1
  • 3
  • 13

3 Answers3

14

Firstly, the below dependency has nothing to do with the issue you are mentioning.

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

Now to answer your question.

The URL http://localhost:8081/swagger-ui/index.html comes from the Swagger-Core library upon which Springdoc is built and thus it will serve the default Petstore example. Though this page can be disabled using the below property in application.properties file.

springdoc.swagger-ui.disable-swagger-default-url=true

But that holds only for version v1.4.1 and above.

Why /v3/api-docs/swagger-config ?

Now in the URl http://localhost:8081/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config the query parameter configUrl specifies from where to fetch the Springdoc's Swagger-specific configuration file.

Now if you actually hit the URL http://localhost:8081/v3/api-docs/swagger-config, you'll get a config file that's similar to the one below

{
  "configUrl": "/v3/api-docs/swagger-config",
  "docExpansion": "none",
  "urls": [
    {
      "url": "/v3/api-docs/default",
      "name": "default"
    }
  ],
  "validatorUrl": ""
}

The urls object encompasses individual objects for each API-group. Each API group is shown in the Swagger-UI as shown below

api-group

Now, for each API group, these properties are used by Springdoc to render the Swagger-UI by fetching the OpenAPI specification file from the given url and the name is rendered as shown in the above image.

As for the docExpansion property, it's set to none as that setting was explicitly specified in my application.properties

Playing with Properties

  • As of Springdoc 1.6.0, the below property is blocked by default for security reasons. Please refer to the comment here for more info. Use springdoc.swagger-ui.queryConfigEnabled=true to enable it at own risk since 1.6.0.

    Use the below property if you want to override the URL from where Springdoc's Swagger configuration file is fetched. Essentially the new URL should return a config file that's similar to the one returned from /v3/api-docs/swagger-config. Defaults to /v3/api-docs/swagger-config

springdoc.swagger-ui.configUrl=/mySpringdocConfig
  • Use the below property to override the URL where your Springdoc's Swagger-UI loads. Defaults to /swagger-ui.html, and that's why Swagger-UI is available at http://localhost:8081/swagger-ui.html
springdoc.swagger-ui.path=/mySwagger-UIPath

Conclusion

  • I don't think it's possible to get rid of the ?configUrl=/v3/api-docs/swagger-config from the URL, as it'll always be available and point to the location from where Sprinfdoc's configuration file will be fetched, which if not available will lead to an error in fetching the configuration file and thus make the Swagger-UI useless. Also, it's something you'll not want to get rid of as it's being used by the framework itself.

  • Refer here for a list of all the supported properties to customize the behavior of Springdoc.

Debargha Roy
  • 2,320
  • 1
  • 15
  • 34
6

You need to access the swagger ui at http://localhost:8081/swagger-ui.html instead of http://localhost:8081/swagger-ui/index.html which loads the pet store default swagger. You can check the work around at

https://github.com/springdoc/springdoc-openapi/issues/43

The url http://localhost:8081/swagger-ui.html will always get redirected to http://localhost:8081/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config.

You can customize with the following in application.properties

springdoc.api-docs.path=/api-docs 
springdoc.swagger-ui.path=/swagger-ui-custom.html

Now the url http://localhost:8081/swagger-ui-custom.html will get redirected to http://localhost:8081/swagger-ui/index.html?configUrl=/api-docs/swagger-config.

Sahit
  • 470
  • 6
  • 15
2

Below configuration helped customising the paths:

springdoc.swagger-ui.path=docs/ui
springdoc.swagger-ui.url=/api/openapi.json
springdoc.swagger-ui.disable-swagger-default-url=true

/api is context path for application

In the browser, I can navigate to http://localhost:8080/docs/ui which further redirects to http://localhost:8080/docs/swagger-ui/index.html as the default behaviour (which seems to be unavoidable). However, configUrl is not present at the end of redirected url.

Dependency used:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.6</version>
</dependency>
Aman
  • 21
  • 3