Spring Boot 整合 Swagger 接口文档工具

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

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

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

本文开发环境：

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

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

添加依赖

我们在 pom.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>

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

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

引入配置

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

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

处理 404

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

我们在 com.launch.config 中新增 WebMvcConfig.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 Boot 实战派》
• SpringBoot教程(十六) | SpringBoot集成swagger（全网最全）
• Swagger Configuration with Spring Boot 3 | Swagger + Spring Boot 3