Adding Swagger UI to Spring Boot projects

This post copies and updates text from a previous version

Check out the previous version of this post if you want to compare the differences.

Spring Boot is a powerful project from the Spring ecosystem which enables developers to maximize their leverage of Spring applications. Standalone projects can be generated at start.spring.io with any other additional dependencies of Spring project included in just a few clicks.

I have created a Spring Boot demo project available on my GitHub. I use this project to demonstrate some tasks I perform regularly in Spring Boot.

Swagger UI

If you’ve been a follower of this blog you might recall I have previously integrated Swagger UI into a Go application (check out this blog post from October 2021).

Swagger is a suite of tools which seeks to provide OpenAPI specifications and definitions. Codebases can be generated from a Swagger doc, just as an existing codebase can be documented by adding Swagger-identifiable annotations.

In this post I will show how I to integrate Springfox Swagger UI into a Spring Boot application. I will then demonstrate integrating Springdoc as an alternative, as Springfox hasn’t been updated in a while (the last commit was Oct, 2020). Springdoc supports the latest version of Spring Boot as of writing (2.7.2).

but first…

How this post is structured

There are three MILE MARKER sections. #1 precedes the relevant code blocks for Springfox. #2 occurs after Springfox is concluded and before Springdoc code blocks begin. #3 appears after the conclusion of Springdoc.

MILE MARKER 1

➡️ Springfox integration (you are here)

🔜 Springdoc integration

Springfox

This configuration uses an existing Spring Boot project and integrates io.springfox/swagger-boot-starter (version 3.0.0).

pom.xml - add Springfox dependency

Add the Springfox Spring Boot starter dependency.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

springfox-boot-starter provides the following artifacts from io.springfox:

• springfox-oas
• springfox-data-rest
• springfox-bean-validators
• springfox-swagger2
• springfox-swagger-ui

Main Application Entry Point - add Springfox annotations

Wherever your Spring Boot app starts is dependent on your project. In my demo application, this is a file called DemoApplication.java.

In this file, only two annotations need to be added to the base class:

@EnableOpenApi
@EnableSwagger2

AppConfiguration.java - add Springfox annotations

If it doesn’t exist yet, create a new Java class called AppConfiguration.java. The class itself will be empty but it will have a few annotations that will enable Springfox to scan the application code and identify endpoints. You could add these annotations on the main application class but I like it this way as it feels more explicit in intention.

@Configuration
@EnableWebMvc
@ComponentScan("dev.michael.demo")
public class AppConfiguration {
}

SpringConfig.java - add Springfox WebMvcConfigurer registries

SpringConfig.java will implement the WebMvcConfigurer interface. It will override a couple of methods so that Spring Boot can serve Swagger UI alongside the Spring Boot app.

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.
    addResourceHandler("/swagger-ui/**")
    .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
    .resourceChain(false);
}

addResourceHandlers will enable Spring Boot to find Swagger resources.

@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addViewController("/swagger-ui/")
    .setViewName("forward:" + "/swagger-ui/index.html");
}

addViewControllers will enable Spring Boot to serve the main Swagger UI page.

Springfox Conclusion

Swagger UI will now automatically generate API documentation every time the Spring Boot application is started.

MILE MARKER 2

✔️ Springfox integration

➡️ Springdoc integration (you are here)

Springdoc

Optional: For an example migration from Springfox to Springdoc, look at this commit on my Redis hackathon repo.

pom.xml - add Springdoc depdendency

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

application.properties - add Springdoc configuration properties

springdoc.packages-to-scan=dev.michaellamb.demo
springdoc.paths-to-match=/api/**
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.enabled=true

Springdoc Conclusion

Springdoc is a bit simpler in configuration than Springfox, relying primarily on application.properties to determine which packages to scan to document HTTP API routes for the app and without needing to override any Spring Beans to serve the frontend.

MILE MARKER 3

✔️ Springfox integration

✔️ Springdoc integration

Great job! 🎉

You have a Spring Boot app ready to start developing an auto-documented HTTP API.