Spring Boot 整合 Swagger 接口文档工具

我们在开发接口的时候，会将接口文档给前端的开发者进行对接。我们可以通过 Postman 或者 Yapi 等接口管理工具进行编写管理。实际开发中，接口的管理确实也应该通过专业的工具管理。

那么，如果只是小团队使用，我们是否可以在边开发的过程中，顺便把接口文档给写了呢？

当然，本文，我们就来谈谈怎么在 Spring Boot 整合 Swagger 接口文档工具。

本文开发环境：

spring boot 版本 2.1.3.RELEASE
java SDK 版本 1.8
mac m1 系统

本文，在笔者之前的项目 Spring Security 简单了解使用基础上开发。

笔者尝试了下整合 swagger3，但是因为原先项目版本的问题，未能整合成功。故整合 swagger2，文档作用都一样，就是页面长得不一样，可以放心使用。

添加依赖

我们在 pom.xml 中添加下面的依赖：

xml 复制代码

<!-- swagger -->
<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>

并在配置文件中添加配置：

xml 复制代码

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

引入配置

在包 com.launch.config 中添加 SwaggerConfig.java 类：

java 复制代码

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 系统") // 标题
                .description("Jimmy Control System") // 描述
                .version("1.0.0") // 版本
                // 姓名，联系 link，邮箱
                .contact(new Contact("Jimmy", "https://juejin.cn/user/1996368846261294", "reng99@outlook.com"))
                .build();
    }

}

到此，我们运行项目，打开连接 http://localhost:8080/swagger-ui/index.html，咦，404 耶～

处理 404

版本的问题，使得我们无法读取 swagger 包下面的页面。那么，我们来重写。

我们在 com.launch.config 中新增 WebMvcConfig.java 文件：

java 复制代码

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/");

    }
}

重新启动，访问路径 http://localhost:8080/doc.html，就可以看到效果。

在本文 Spring Security 简单了解使用中，我们已经开发好了六个接口。点击进入其中一个，比如 queryAll 查询所有用户的接口，可看到其文档：

我们还可以对该接口进行调试：

感兴趣的读者可以自行尝试。

参考

《Spring Boot 实战派》
SpringBoot教程(十六) | SpringBoot集成swagger（全网最全）
Swagger Configuration with Spring Boot 3 | Swagger + Spring Boot 3