【Spring boot框架】Spring boot集成Swagger

前言

提示：这里可以添加本文要记录的大概内容：

例如：随着人工智能的不断发展，机器学习这门技术也越来越重要，很多人都开启了学习机器学习，本文就介绍了机器学习的基础内容。

提示：以下是本篇文章正文内容，下面案例可供参考

一、Swagger是什么？

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步

二、Swagger跟Spring boot集成版本？

1、Swagger 版本

2、spring boot版本

springboot 2.3.5 – springboot 2.7.8，建议不要用3.0之后的版本，目前发现有兼容写问题，大家要好的建议欢迎推荐

二、使用步骤

POM文件添加Swagger jar

1、swagger2 集成方式

swagger2.0需要springfox-swagger2和springfox-swagger-ui,如下：

<!--集成旧版本版本swagger 2.0 需要springfox-swagger2和springfox-swagger-ui-->
<parent>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-parent</artifactId>
	<version>2.2.5.RELEASE</version>
	<relativePath/> <!-- lookup parent from repository -->
</parent>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
     <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2、swagger 3集成

swagger3.0需要springfox-boot-starter,如下：

<parent>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-parent</artifactId>
	<version>2.2.5.RELEASE</version>
	<relativePath/> <!-- lookup parent from repository -->
</parent>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-boot-starter</artifactId>
	<version>3.0.0</version>
</dependency>

添加配置文件

在resource->config配置文件中添加swagger配置文件， 3.0版本后不需要在加入@enableopenapi，和@enableswagger2这两个注解

1、swagger2配置文件

swagger2配置文件需要EnableSwagger2注解，项目启动类型添加@enableopenapi

@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhj.it.msa.common.boot.app"))
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Swagger2接口文档")
                //版本号
                .version("1.0")
                //描述
                .description("Spring Boot中使用Swagger2构建RESTful APIs")
                .build();

    }
}

2、swagger3配置文件

@Configuration //声明该类为配置类
public class Swagger3Config {

    @Bean
    public Docket createRestApi(){
        return  new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build().globalRequestParameters(globalRequestParameters()).enable(true);
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("Spring Boot中使用Swagger3构建RESTful APIs")
                .version("1.0")
                .build();
    }

3、 swagger知识扩展

需要在swagger添加一些默认参数，添加globalRequestParameters方式，比如接口定义默认需要输入语言、和租户ID，可以添加如下配置，还可以配置是否必填

 private List<RequestParameter> globalRequestParameters(){
        RequestParameterBuilder tenantid=new RequestParameterBuilder();
        tenantid.name("X-Tenant-Id").description("租户ID").in(ParameterType.HEADER).required(false);
        RequestParameterBuilder lang=new RequestParameterBuilder();
        lang.name("X-Lang-Id").description("语言标准编码").in(ParameterType.HEADER).required(false);
        List<RequestParameter> parameters=new ArrayList<>();
        parameters.add(tenantid.build());
        parameters.add(lang.build());
        return parameters;
    }

4、 FAQ

问题1、spring boot 2.6以上版本集成swagger 3.0版本冲突问题
解决方案一、spring boot 版本降低到2.6版本以下
解决方案二、在application.yml中添加以下配置：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

总结

1、POM添加Swagger jar包，但是主要spring boot 版本
2、添加swagger配置文件
3、启动访问swagger，