Spring Boot 整合 Swagger 接口文档工具

Jimmy_is_jimmy

发布于 2023-08-09 18:33:45

31800

代码可运行

文章被收录于专栏：call_me_Rcall_me_R

运行总次数：0

代码可运行

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

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

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

本文开发环境：

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

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

笔者尝试了下整合 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 类：

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 文件：

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，就可以看到效果。