Learn how to generate documentation for your Spring Boot application using Springfox Boot Starter. This article extends the Spring Boot API documentation with Swagger post.
In order to see an example Spring Boot project where the starter replaced the older Springfox version, visit the 951ba8dc0fd805c21daf8a483ab730b19f30677f commit.
Add Springfox Boot starter
First, add the maven dependency to your pom.xml
file:
|
<!-- pom.xml --> … <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> … |
Second, create a class where we’re going to configure Swagger docs, like in my example SwaggerConfig.java file from the scrum_ally
project:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
|
package in.keepgrowing.scrumally.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import static springfox.documentation.builders.PathSelectors.regex; @Configuration public class SwaggerConfig { @Bean public Docket scrumAllyApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .paths(regex("/api.*")) .build() .apiInfo(apiInfo()); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Scrum_ally API") .description("Scrum_ally is a web application designed for project management") .license("MIT License") .licenseUrl("https://opensource.org/licenses/MIT") .build(); } } |
Finally, we have to configure handling resources. You’ll find the example config from the Springfox documentation below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
|
public class SwaggerUiWebMvcConfigurer implements WebMvcConfigurer { private final String baseUrl; public SwaggerUiWebMvcConfigurer(String baseUrl) { this.baseUrl = baseUrl; } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { String baseUrl = StringUtils.trimTrailingCharacter(this.baseUrl, '/'); registry. addResourceHandler(baseUrl + "/swagger-ui/**") .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/") .resourceChain(false); } @Override public void addViewControllers(ViewControllerRegistry registry) { registry.addViewController(baseUrl + "/swagger-ui/") .setViewName("forward:" + baseUrl + "/swagger-ui/index.html"); } } |
The scrum_ally project uses Angular, so the its configuration is a little bit different, you can find it in the MvcConfiguration file.
In the end, we can finally start our app and see the documentation. We should be able to get the project specification in json by calling the http://localhost:8080/v3/api-docs endpoint (example in Postman):
Furthermore, we also can see the documentation in Swagger UI on http://localhost:8080/swagger-ui/:
Adjust the security config
In order to allow all GET requests to the documentation resources when your project uses Spring Boot security starter, add this matcher to your config:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
|
// scrum-ally/backend/src/main/java/in/keepgrowing/scrumally/config/SecurityConfig.java … @Configuration public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter { @Override protected void configure(HttpSecurity httpSecurity) throws Exception { http … .authorizeRequests() … .antMatchers( HttpMethod.GET, "/v2/api-docs", "/swagger-resources/**", "/swagger-ui.html**", "/webjars/**", "favicon.ico" ).permitAll() … .anyRequest().authenticated(); … } } … |
Useful links
Photo by Andrea Piacquadio from Pexels
Related:
Shipping an application to the production requires reliable mechanisms responsible for auditing, health checks, and metrics collection. Fortunately, with Spring Boot we can apply those features effortlessly and monitor an app with Actuator. What we're going to build In this article you can read how to: add Actuator to a…
We're going to apply Basic Auth on API calls made from Swagger UI. OpenAPI allows us to provide security configuration for calling our documented endpoints and offers a few security schemes. Once we have our Spring Security configured and endpoints secured, we can show a project documentation to everyone, and…
Apart from having logs displayed directly in the console, we can configure our Spring Boot project to write log entries into files. It not only allows us to easily store and share logs for debugging, but also can be the first step towards browsing them in Kibana. What we are…