Spring Boot integrates Swagger interface documentation tool

When we develop interfaces, we will provide the interface documents to front-end developers for docking. We can write and manage through interface management tools such as Postman or Yapi. In actual development, interface management should indeed be managed through professional tools.

So, if it is only used by a small team, can we write the interface document during the development process?

Of course, in this article, we will talk about how to integrate the Swagger interface documentation tool in Spring Boot.

The development environment of this article:

• spring boot version 2.1.3.RELEASE

• java SDK version 1.8

• mac m1 system

This article is developed based on the author’s previous project Spring Security, which is a simple understanding and use [1].

The author tried to integrate swagger3, but due to problems with the original project version, the integration failed. Therefore, by integrating swagger2, the document function is the same, but the page length is different, so you can use it with confidence.

Add dependencies

We add the following dependencies in pom.xml:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

And add configuration in configuration file:

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

Introduce configuration

Add the SwaggerConfig.java class in package com.launch.config:

package com.launch.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.launch.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Launch System")
                .description("Jimmy Control System")
                .version("1.0.0")
                
                .contact(new Contact("Jimmy", "https://juejin.cn/user/1996368846261294", "[email protected]"))
                .build();
    }

}

At this point, we run the project and open the connection http://localhost:8080/swagger-ui/index.html. Hey, 404 yeah~

Handling 404

A version problem prevents us from reading the pages under the swagger package. So, let’s rewrite.

We added the WebMvcConfig.java file in com.launch.config:

package com.launch.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;


@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");

    }
}

Restart and access the path http://localhost:8080/doc.html to see the effect.

In this article, a brief understanding of the use of Spring Security [2], we have developed six interfaces. Click to enter one of them, such as queryAll to query all user interfaces, and you can see its documentation:

We can also debug this interface:

Interested readers can try it themselves.

Reference

• “Spring Boot Practical School”

• SpringBoot tutorial (16) | SpringBoot integrated swagger (the most complete in the entire network) [3]

• Swagger Configuration with Spring Boot 3 | Swagger + Spring Boot 3[4]

Reference materials

[1]

https://juejin.cn/post/7261954917681283109: https://juejin.cn/post/7261954917681283109

[2]

https://juejin.cn/post/7261954917681283109: https://juejin.cn/post/7261954917681283109

[3]

https://lsqingfeng.blog.csdn.net/article/details/123678701: https://link.juejin.cn/?target=https://lsqingfeng.blog.csdn.net/article/details/ 123678701

[4]

https://www.youtube.com/watch?v=Eo6v01KUeZM: https://link.juejin.cn/?target=https://www.youtube.com/watch?v=Eo6v01KUeZM

The knowledge points of the article match the official knowledge files, and you can further learn related knowledge. Java Skill TreeHomepageOverview 138,184 people are learning the system