swagger实现对API接口的版本管理

最新推荐文章于 2024-05-31 12:50:00 发布

西楚子羽

最新推荐文章于 2024-05-31 12:50:00 发布

阅读量910

点赞数 1

文章标签： java spring boot

本文链接：https://blog.csdn.net/qq_43610975/article/details/130271874

版权

当我们在开发API时，接口的版本管理是一个比较重要的话题。虽然Swagger是一个广泛使用的API文档工具，可以轻松地生成API文档和与之对应的Swagger UI，但是随着我们项目的迭代更新，接口数量将不断增加，导致我们很难记得每个版本中都包含哪些接口。因此，本文将介绍如何借助Swagger实现接口的版本管理，以便更好地管理和使用接口，提高开发效率。

一、maven依赖

这里我们引入2.9.2版本，在引入的时候排除swagger-annotations、swagger-models依赖重新引入1.5.21版本来解决当我们访问swagger页面的时候程序控制台报错的问题，完整pom依赖如下

<parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency><dependency>
        <groupId>com.github.pagehelper</groupId>
            <artifactId>pagehelper-spring-boot-starter</artifactId>
            <version>1.3.0</version>
        </dependency>

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>

        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>1.2.73</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
        <dependency>
            <groupId>com.github.pagehelper</groupId>
            <artifactId>pagehelper-spring-boot-starter</artifactId>
            <version>1.4.1</version>
        </dependency>
    </dependencies>

二、application.yml文件配置

我们在配置文件中配置需要生成哪些版本的接口，这里生成v1.0、v2.0、v3.0三个版本

swagger:
  open: true
  version: v1.0,v2.0,v3.0

三、程序配置

1.新建版本标记注解

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ApiVersion {

    /**
     * 接口版本号
     * @return
     */
    String[] group();
}

2.添加SwaggerConfig配置类

import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
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;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig{

    private final ConfigurableApplicationContext applicationContext;

    private final List<String> versions;

    @Autowired
    public SwaggerConfig(ConfigurableApplicationContext applicationContext, @Value("${swagger.version}") List<String> versions){
        this.applicationContext = applicationContext;
        this.versions = versions;
    }

    /**
     * 默认分组default
     * @return
     */
    @Bean
    public Docket createRestApi() {
        // 创建版本信息
        createVersions();
        // 配置Docket实例
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建各个版本的Docket实例并注册到Spring容器中
     */
    private void createVersions() {
        for (String version : versions) {
            // 创建当前版本的Docket实例
            Docket docket = apiDocket(version);
            // 将Docket实例注册到Spring容器中，使用Docket名称作为bean名称
            applicationContext.getBeanFactory().registerSingleton(docket.toString(), docket);
        }
    }

    /**
     * 使用指定的版本号创建Docket实例
     * @param version 版本号
     * @return Docket实例
     */
    private Docket apiDocket(String version) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName(version)
                .select()
                .apis(withVersion(version))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建谓词，用于判断Controller是否匹配当前版本
     * @param version 版本号
     * @return 谓词
     */
    private Predicate<RequestHandler> withVersion(String version) {
        return Predicates.and(
                // 包含@Api注解的类
                RequestHandlerSelectors.withClassAnnotation(Api.class),
                // 包含@ApiOperation注解的方法
                RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class),
                // 版本号匹配
                handler -> versionMatches(handler, version)
        );
    }

    /**
     * 判断指定的Controller方法是否匹配版本号
     * @param handler Controller方法
     * @param version 版本号
     * @return 是否匹配版本号
     */
    private boolean versionMatches(RequestHandler handler, String version) {
        ApiVersion apiVersion = handler.getHandlerMethod().getMethodAnnotation(ApiVersion.class);
        return apiVersion != null && Arrays.asList(apiVersion.group()).contains(version);
    }

    /**
     * 创建ApiInfo对象，用于配置Swagger页面信息
     * @return ApiInfo对象
     */
    private ApiInfo apiInfo() {
        Contact contact = new Contact("作者", "", "**********@qq.com");
        return new ApiInfo(
                "XXX系统接口",
                "包含系统内所有可用接口说明",
                "v1.0",
                "",
                contact,
                "",
                "",
                new ArrayList<>()
        );
    }
}

3.在我们的接口中标记属于哪个版本

@RestController
@RequestMapping("/product")
@Api(tags = "(Product)")
public class ProductController {
    /**
     * 服务对象
     */
    @Resource(name = "productService")
    private ProductService productService;
    
    /**
     * 分页查询数据
     *
     * @return 实例对象集合
     */
    @ApiVersion(group = {"v1.0","v2.0"})
    @ApiOperation(value = "分页查询数据")
    @GetMapping("/page/{pageNum}/{pageSize}")
    public ResponseEntity<List> queryByPage(@ApiParam(name = "pageNum", value = "当前页") @PathVariable(name = "pageNum") int pageNum, @ApiParam(name = "pageSize", value = "每页条数") @PathVariable(name = "pageSize") int pageSize) {
        return ResponseEntity.ok(new ArrayList());
    }
    
    /**
     * 通过主键查询单条数据
     *
     * @param id 主键
     * @return 单条数据
     */
    @ApiVersion(group = {"v1.0","v3.0"})
    @ApiOperation(value = "通过id主键查询单条数据")
    @GetMapping("/{id}")
    public ResponseEntity<ProductVO> selectByPrimaryKey(@ApiParam(name = "id", value = "id主键") @PathVariable(name = "id") Integer id) {
        return ResponseEntity.ok(new ProductVO());
    }

    /**
     * 新增单条数据
     *
     * @param product 实体
     * @return 新增结果
     */
    @ApiVersion(group = {"v3.0"})
    @ApiOperation(value = "新增单条数据")
    @PostMapping
    public ResponseEntity<Integer> insertSelective(@ApiParam(name = "product", value = "对象") @RequestBody ProductQuery product) {
        return ResponseEntity.ok(1);
    }
}

4.浏览器访问swagger页面，
default分组包含所有的接口
在这里插入图片描述

v1.0版本含有两个接口
在这里插入图片描述

v2.0版本含有一个接口
在这里插入图片描述
v3.0含有两个接口

在这里插入图片描述

西楚子羽

关注

1
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
swagger实现对API接口的版本管理

当我们在开发API时，接口的版本管理是一个比较重要的话题。虽然Swagger是一个广泛使用的API文档工具，可以轻松地生成API文档和与之对应的Swagger UI，但是随着我们项目的迭代更新，接口数量将不断增加，导致我们很难记得每个版本中都包含哪些接口。因此，本文将介绍如何借助Swagger实现接口的版本管理，以便更好地管理和使用接口，提高开发效率。
复制链接

扫一扫