使用Swagger实现接口版本号管理方式

目录
  • Swagger实现接口版本号管理
  • 使用swagger测试接口

Swagger实现接口版本号管理

前言:使用swagger暴露对外接口时原则是每个系统在不同的迭代版本仅仅需要暴露该迭代版本的接口给外部使用,客户端不需要关心不相关的接口

先来看张效果图

下面是实现代码:

定义注解ApiVersion:

/**
 * 接口版本管理注解
 * @author 周宁
 * @Date 2018-08-30 11:48
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ApiVersion {

    /**
     * 接口版本号(对应swagger中的group)
     * @return String[]
     */
    String[] group();

}

定义一个用于版本常量的类ApiVersionConstant

/**
 * api版本号常量类
 * @author 周宁
 * @Date 2018-08-30 13:30
 */
public interface ApiVersionConstant {
    /**
     * 图审系统手机app1.0.0版本
     */
    String FAP_APP100 = "app1.0.0";

}

更改SwaggerConfig添加Docket(可以理解成一组swagger 接口的集合),并定义groupName,根据ApiVersion的group方法区分不同组(迭代)的接口,代码如下:

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {

    //默认版本的接口api-docs分组
    @Bean
    public Docket vDefault(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.gysoft"))//controller路径
                .paths(PathSelectors.any())
                .build();
    }
    //app1.0.0版本对外接口
    @Bean
    public Docket vApp100(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())
                .groupName(FAP_APP100)
                .select()
                .apis(input -> {
                    ApiVersion apiVersion = input.getHandlerMethod().getMethodAnnotation(ApiVersion.class);
                    if(apiVersion!=null&&Arrays.asList(apiVersion.group()).contains(FAP_APP100)){
                        return true;
                    }
                    return false;
                })//controller路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo buildApiInf(){
        return new ApiInfoBuilder()
                .title("接口列表")
                .termsOfServiceUrl("http://127.0.0.1:8080/swagger-ui.html")
                .description("springmvc swagger 接口测试")
                .version("1.0.0")
                .build();
    }
}

立即食用

/**
 * @author 周宁
 * @Date 2018-08-24 11:05
 */
@RestController
@RequestMapping("/document")
@Api(value = "资料文档或者CAD图纸", description = "资料文档或者CAD图纸")
public class DocumentController extends GyBasicSession {

    private static final Logger logger = LoggerFactory.getLogger(DocumentController.class);

    @ApiImplicitParams({@ApiImplicitParam(name = "page", value = "当前页数", dataType = "int", paramType = "path"),
            @ApiImplicitParam(name = "pageSize", value = "每页大小", dataType = "int", paramType = "path"),
            @ApiImplicitParam(name = "projectId", value = "项目id", dataType = "string", paramType = "path"),
            @ApiImplicitParam(name = "stageNum", value = "阶段编号", dataType = "string", paramType = "path"),
            @ApiImplicitParam(name = "type", value = "0资料(文档);1cad图纸", dataType = "int", paramType = "path"),
            @ApiImplicitParam(name = "searchkey", value = "搜索关键字", dataType = "string", paramType = "query")})
    @ApiOperation("分页获取资料文档(CAD图纸)列表数据")
    @GetMapping("/pageQueryAppDocumentInfo/{page}/{pageSize}/{projectId}/{stageNum}/{type}")
    @ApiVersion(group = ApiVersionConstant.FAP_APP100)
    public PageResult<AppDocumentInfo> pageQueryAppDocumentInfo(@PathVariable Integer page, @PathVariable Integer pageSize, @PathVariable String projectId, @PathVariable String stageNum, @PathVariable Integer type, @RequestParam String searchkey) {
        return null;
    }
}

使用swagger测试接口

swagger:自动扫描 controller 包下的请求,生成接口文档,并提供测试功能。

引入依赖

       <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

在 config 包引入 swagger 自定义配置类

package com.zhiyou100.zymusic.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;
/**
 * @author teacher
 * @date 2019/9/25
 */
@Configuration
@EnableSwagger2
public class MySwaggerConfiguration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //标题
                .title("Spring Boot 中使用 Swagger2 构建 RESTful APIs")
                //简介
                .description("hello swagger")
                //服务条款
                .termsOfServiceUrl("1. xxx\n2. xxx\n3. xxx")
                //作者个人信息
                .contact(new Contact("admin", "http://www.zhiyou100.com", "admin@zhiyou100.com"))
                //版本
                .version("1.0")
                .build();
    }
}

启动项目后,使用 http://localhost:8080/swagger-ui.html

选择需要测试的接口:Try it out -> 填写参数 -> Execute -> 查看响应

以上为个人经验,希望能给大家一个参考,也希望大家多多支持我们。

时间: 2021-10-11

swagger添加权限验证保证API(接口)安全性(两种方法)

当我们使用swagger,进行接口测试,怕接口不安全,担心暴露.可采用两种方式 1.环境权限配置 对swagger文档配置只在测试环境可访问,生产环境不可访问. @Profile({"dev","test"}) 如以上配置,则只有在dev以及test环境有效,在生产环境不可访问. 2.账户权限配置 在1.9.0版本时,针对Swagger的资源接口,SwaggerBootstrapUi提供了简单的Basic认证功能. 如果是springboot项目可在yml文件配置

Swagger屏蔽某些接口显示的操作

Swagger屏蔽某些接口显示 首先说下为什么要屏蔽,因为某些接口是针对内部服务调用的,不需要进行对接.显示出来的话: 1.容易混淆 2.容易暴露相关接口内容 其实屏蔽的话比较简单,主要是注解: @ApiIgnore @RequestMapping("/wx/back") @ApiIgnore public String wxBack(HttpServletRequest request){ return payService.back(ParamUtil.getXmlString(r

教你利用springboot集成swagger并生成接口文档

效果图 实现步骤 1.maven中引入jar包,不同版本的swagger可能页面效果不一样. <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.1</version> </dependency> <dependency> <groupId&g

解决swagger2.9.2接口文档显示的问题

swagger2.9.2接口文档显示 swagger版本:2.9.2 框架:springboot2.1.2 当没有使用 @ApiImplicitParam和response=Resp.class时,swagger会自动去显示接口入参对象的各属性,及响应的对象属性,如下图: 而如果加入@ApiImplicitParam和response=Resp.class时,则没有任务字段属性显示,如下: 所以建议,当接口的入参为几个字段属性时可以加上@ApiImplicitParam进行描述,如果是对象,则只

Java之Swagger配置扫描接口以及开关案例讲解

1. Swagger--配置扫描接口及开关 1.1 配置扫描接口 SwaggerConfig.java /** * 配置docket以配置Swagger具体参数 */ @Bean public Docket docket() { /* * 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口 * basePackage(final String basePackage) // 根据包路径扫描接口(最常用) * any() 扫描所有,项目中的所

深入浅析java web log4j 配置及在web项目中配置Log4j的技巧

在上篇文章给大家介绍了Java log4j详细教程,本文给大家介绍java web log4j配置及web项目中配置log4j的技巧.具体详情请看下文吧. 首先给大家提供log4j.jar下载:http://logging.apache.org/log4j/1.2/download.html 一.java web项目使用log4j 1.在web.xml文件中添加 <!-- 配置log4j --> <context-param> <param-name>webAppRoo

浅谈Java 三种方式实现接口校验

本文介绍了Java 三种方式实现接口校验,主要包括AOP,MVC拦截器,分享给大家,具体如下: 方法一:AOP 代码如下定义一个权限注解 package com.thinkgem.jeesite.common.annotation; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import j

obix协议在java中的配置和使用详解

前言 本文主要给大家介绍的是关于obix协议在java中的配置和使用,分享出来供大家参考学习,下面话不多说了,来一起看看详细的介绍吧. 什么是 oBIX? 简单来讲,obix是一种 XML 通讯协议,使用Http Request/Post方式进行数据通讯.所有数据通过可读字符进行传送,一个oBIX对象可以有唯一的一个URL识别. oBIX的实现原理 首先数据储存在Niagara的服务平台上,我们需要做的是从Niagara获取数据,并且储存在InfluxDB中.下面是实现的流程方法. 加粗 Ctr

Spring装配Bean之用Java代码安装配置bean详解

前言 本文主要给大家介绍了关于Spring之利用Java代码安装配置bean的相关内容,尽管通过组件扫描和自动装配实现Spring的自动化配置很方便也推荐,但是有时候自动配置的方式实现不了,就需要明确显示的配置Spring.比如说,想要将第三方库中的组件装配到自己的应用中,这样的情况下,是没办法在它的类上添加 @Compnent和 @Autowired注解的. 在这种情况下,需要使用显示装配的方式,可以分别通过Java和XML实现,推荐使用Java的方式,因为更加强大,类型安全并且重构友好,因为

Java编程实现NBA赛事接口调用实例代码

第一步:找别人提供的接口,比如在这里我选择的是聚合数据提供的接口 第二步:要申请相应的AppKey方可使用,此参数会作为接口的参数调用. 第三步:调用别人提供的接口方法 代码如下: package juheapi.nba; /** * Created by Administrator on 2017/11/19/019. */ import net.sf.json.JSONObject; import java.io.*; import java.net.HttpURLConnection; i

在Spring中基于Java类进行配置的完整步骤

前言 JavaConfig 原来是 Spring 的一个子项目,它通过 Java 类的方式提供 Bean 的定义信息,在 Spring4 的版本, JavaConfig 已正式成为 Spring4 的核心功能 . 本文将详细介绍关于Spring中基于Java类进行配置的相关内容,下面话不多说了,来一起看看详细的介绍吧 1 定义 Bean 普通的 POJO 只要标注了 @Configuration 注解,就可以为 Spring 容器提供 Bean 的定义信息. @Configuration pub

Linux学习第二篇 Java环境安装配置教程

本文教程为大家分享了Java环境安装配置,供大家参考,具体内容如下 jdk版本:jdk-8u131-linux-x64.rpm 注:以下操作在root用户或具有root权限的用户下操作 一.将 dk-8u131-linux-x64.rpm拷贝到/home目录下 cp jdk-8u131-linux-x64.rpm /home/ 二.解压rpm文件 rpm -ivh jdk-8u131-linux-x64.rpm 三.环境变量的配置 注:环境变量的配置稍微麻烦一点,不过也不是特别难. 1.输入以下

java实现接口的典型案例

废话不多说,直接上代码 package com.car; interface Carr{ //汽车名称 String getName(); //获得汽车售价 int getPrice(); } class BMW implements Carr{ public String getName(){ return "BMW"; } public int getPrice(){ return 300000; } } class CheryQQ implements Carr{ public

Java 开发环境配置步骤(介绍)

背景 当要求系统启动一个应用程序时,系统会先查找当前命令是否是内部命令,若不是,则在当前目录下查找,如果仍没有找到,则在系统变量 Path 指定的路径去查找.JDK(Java Development Kit)包含了一系列开发工具,这些开发工具都在 JDK 的安装目录下,为了方便使用这些开发工具,我们有必要把 JDK 的安装目录设置了系统变量. 步骤 为了配置 JDK 的系统变量环境,我们需要设置三个系统变量,分别是 JAVA_HOME(可选),Path 和 CLASSPATH,下面是这三个变量的

Java开发环境配置教程(win7 64bit)

Java开发环境配置(win7-64bit) 1.概述 搭建Java开发环境一般需要同时安装JDK和JRE.JDK:指Java开发工具包Java Development Kit,开发Java程序时必需,JDK里包含一部分公共JRE.JRE:一个Java运行环境Java Runtime Environment,运行已开发的Java程序时所用. 2.文本用到的工具 Java SE基础工具包:官网下载 (版本很多,自行选择适用版本,省略安装过程,安装时候下一步下一步即可) 3.环境变量配置 Java环