Thursday, October 24, 2019

Setting up Spring Boot with SpringDoc OpenApi UI

to add springdoc openapi ui to a project is very easy, just add

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

to your project.  you can than access the swagger UI with /swagger-ui.html.

my spring boot app also serve the static UI with context path / (root) and are packaged under classpath:/statics.  This is one of the default path Spring autoconfig provides.  The problem is with springdoc-openapi-ui, the static page won't work anymore.  Turns out, it because springdoc-openapi-ui has a SwaggerConfig configuration which will add a resource handler, like this.

if(swaggerPath.contains("/") uiRootPath = swaggerPath.substring(0, swaggerPath.lastIndexOf('/'));
registry.addResourceHandler( uiRootPath + "/**").addResourceLocations(WEB_JARS_PREFIX_URL + "/").resourceChain(false);

defaul swaggerPath is "/swagger-ui.html", thus uiRootPath resolves to an empty string.

This prevents the resource handler spring autoconfig added from working as both are binded to /**.

To resolve this, we just have to set swaggerPath to something with more than one level.  e.g.

springdoc.swagger-ui.path=/swagger/apidoc.html

This will add the /webjars/ directory to /swager/** instead.