springfox-bridge：随心所欲地为非restful接口生成swagger api文档

2021-08-19 07:29:26

一、引言

目前，利用swagger框架为restful接口编写API文档非常流行，在spring web项目中，利用springfox+swagger更是可以通过注解的方式直接进行API文档的生成，这样开发者在项目开发的同时就直接把文档准备好了，利用springfox的配置，可以在项目启动后直接浏览器访问查看API文档，同时还能在界面直接进行API的测试。springfox的使用本文不在此赘述了，现在引出一个问题: 非restful接口能否采用swagger生成接口文档？

在项目中集成springfox-bridge可以快速的为非restful接口生成API文档，编写文档的方式跟springfox一样简单，在相关类或者接口上采用注解的方式定义文档信息即可。

springfox-bridge相当于架设了一座与springfox之间的桥梁，通过动态生成配置了springfox注解的mvc接口并进行注册，形成对非restful接口生成swagger文档的能力。

项目github地址: https://github.com/double-bin/springfox-bridge

二、springfox-bridge特性说明

启动简单
- 在springboot项目中，集成springfox-bridge-spring-boot-starter即可自动启动；
- 在非springboot项目中，通过实现ApplicationContextAware接口，通过SpringfoxBridge.start(ApplicationContext context)方法,并配置@EnableSwagger2注解即可快速启动。
兼容性强
- 与协议无关，不挑协议，无论你是使用dubbo、ServiceComb还是其它种种，只要项目本身启用了springmvc, 相应的接口注册了spring bean, 就能像使用springfox那样使用springfox-brige，用注解的方式为接口生成文档。
- 更进一步的讲，只要满足上述条件的spring bean, 即使不是controller层的接口，也能使用springfox-bridge进行文档生成。
简单的注解
- springfox-bridge提供了几个简单的注解供开发使用，注解的使用方式与springfox的类似，主要在类/接口、方法上进行文档的定义。
方便的分组
- 采用@BridgeGroup注解可以方便的为项目的接口文档进行分组，而无需手动的配置Docket，springfox-bridge自动按照@BridgeGroup的注解值将文档进行分组归类。
不影响原有文档
- springfox-bridge通过分组隔离，项目中原先使用springfox为restful接口生成的文档，不会受到springfox-bridge的影响
方法入参不限定请求体的数量
- 原生springfox对restful请求生成文档，而restful只支持一个请求体入参（用@RequestBody注解标识）。springfox-bridge没有这个限制。
支持界面测试
- 跟springfox生成文档可以通过界面直接调用一样，springfox-bridge同样支持

三、使用说明

使用springfox-bridge需要项目本身启用了springmvc框架， spring相关依赖版本在spring3.1以上

3.1 配置maven依赖

1）使用了springboot的项目：

        <dependency>
            <groupId>com.github.double-bin</groupId>
            <artifactId>springfox-bridge-spring-boot-starter</artifactId>
            <version>1.0.3</version>
        </dependency>

2) 非springboot项目：

        <dependency>
            <groupId>com.github.double-bin</groupId>
            <artifactId>springfox-bridge-core</artifactId>
            <version>1.0.3</version>
        </dependency>

3.2 启动配置

1）使用了springboot的项目

配置了springfox-bridge-spring-boot-starter后，默认开启springfox-bridge。
如果需要关闭，可以在application.properties文件(或yml文件)中配置springfox.bridge.enabled的值为false即可

2) 非springboot项目：

可通过配置类实现ApplicationContextAware接口的setApplicationContext方法，方法实现中通过SpringfoxBridge.start()方法启动springfox-bridge, 配置类上通过@EnableSwagger2启动springfox基本功能，可参考：

import org.springframework.beans.BeansException;
import org.springframework.context.ApplicationContext;
import org.springframework.context.ApplicationContextAware;
import org.springframework.context.annotation.Configuration;
import com.github.doublebin.springfox.bridge.core.SpringfoxBridge;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@EnableSwagger2
@Configuration
public class MyXXXConfiguration implements ApplicationContextAware {
    @Override
    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
        SpringfoxBridge.start(applicationContext);

    }
}

3.3 使用示例

下面示例代码演示如何使用springfox-bridge的注解，如何定义的文档，如果设置分组等，展示结果请看3.4

1, 定义两个请求的model类：TestRquest1和TestRequest2

model类中可以使用springfox的原生注解：io.swagger.annotations.ApiModel和io.swagger.annotations.ApiModelProperty

package com.github.doublebin.springfox.bridge.demo.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@ApiModel(value="TestRequest1", description = "测试请求体1")
public class TestRequest1 {

    @ApiModelProperty(value = "唯一id", required = true)
    private long uuid;

    @ApiModelProperty(value = "名字", required = true)
    private String name;
}

package com.github.doublebin.springfox.bridge.demo.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@ApiModel(value="TestRequest2", description = "测试请求体2")
public class TestRequest2 {

    @ApiModelProperty(value = "名字", required = true)
    private String name;

    @ApiModelProperty(value = "描述", required = true)
    private String desc;
}

2, 定义三个service类，并标注@Service供spring扫描并注册bean。

package com.github.doublebin.springfox.bridge.demo.service;

import com.github.doublebin.springfox.bridge.demo.model.TestRequest1;
import com.github.doublebin.springfox.bridge.demo.model.TestRequest2;
import org.springframework.stereotype.Service;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeApi;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeGroup;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeModelProperty;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeOperation;

@Service
@BridgeApi(value = "TestService1 Apis", description = "测试服务1")
@BridgeGroup("test-group1")
public class TestService1 {

    @BridgeOperation(value = "测试查询1", notes = "测试查询方法1说明")
    public String testQuery(@BridgeModelProperty(value = "用户id", required = true) long id, @BridgeModelProperty(value = "请求2", required = false) TestRequest1 request){
        return "Test query success, id is " + id;
    }

    @BridgeOperation(value = "测试查询2", notes = "测试查询方法2说明")
    public String testQuery(@BridgeModelProperty(value = "用户id", required = true) long id){
        return "Test query success, id is " + id;
    }

    @BridgeOperation(value = "测试查询3", notes = "测试查询方法3说明")
    public String testQuery(){
        return "Test query success.";
    }

    @BridgeOperation(value = "测试查询4", notes = "测试查询方法4说明")
    public String testQuery(@BridgeModelProperty(value = "用户id", required = true) long id, @BridgeModelProperty(value = "请求2", required = false) TestRequest2 request){
        return "Test query success, id is " + id;
    }

}

package com.github.doublebin.springfox.bridge.demo.service;

import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeApi;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeGroup;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeModelProperty;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeOperation;
import com.github.doublebin.springfox.bridge.demo.model.TestRequest1;
import org.springframework.stereotype.Service;

@Service
@BridgeApi(value = "TestService2 Apis", description = "测试服务2")
@BridgeGroup("test-group2")
public class TestService2 {
    @BridgeOperation(value = "测试查询", notes = "测试查询方法说明")
    public String testQuery(@BridgeModelProperty(value = "用户id", required = true) long id, @BridgeModelProperty(value = "请求2", required = false) TestRequest1 request){
        return "Test query success, id is " + id;
    }
}

package com.github.doublebin.springfox.bridge.demo.service;

import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeApi;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeGroup;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeModelProperty;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeOperation;
import com.github.doublebin.springfox.bridge.demo.model.TestRequest1;
import org.springframework.stereotype.Service;

@Service
@BridgeApi(value = "TestService3 Apis", description = "测试服务3")
@BridgeGroup("test-group1")
public class TestService3 {
    @BridgeOperation(value = "测试查询", notes = "测试查询方法说明")
    public String testQuery(@BridgeModelProperty(value = "用户id", required = true) long id, @BridgeModelProperty(value = "请求2", required = false) TestRequest1 request){
        return "Test query success, id is " + id;
    }
}

示例中定义了2个分组：test-group1 和 test-group2，其中TestService1和TestService3归属于test-group1分组，TestService2归属于test-group2分组，其中TestService1中定义了多个不同的方法，在3.4节中会展示这些情况下的多个效果

3.4 示例效果展示

浏览器访问地址：http:${host}:${port}/${server.context-path}/swagger-ui.html

首先看下面两个分组的截图，其中test-group1:

test-group2:

说明:

用spring-fox对某个类生成API文档，必须用在类上使用@BridgeApi注解，并在需要生成文档的方法上使用@BridgeOperation注解。
如果要对某个类分组，可以在类上标识@BridgeGroup注解。前面示例中，通过@BridgeGroup注解定义了2个分组，将3个Service类进行了归类，在上面两图可以看到，通过下拉框切换分组后，将分别展示@BridgeGroup注解定义的不同分组的页面。当然@BridgeGroup如果不定义，springfox-bridge会生成一个名为defafult的分组，将没有显式定义@BridgeGroup注解的文档归类到default分组下。
swagger页面上类的tag采用类全名的方式展示，@BridgeApi注解的description值也会展示在界面上描述类的作用。
@BridgeOperation注解定义方法，springfox-bridge会在对应的类tag下生成对应的方法tag，由图可以看出，path路径的组成格式为：“/类全名/方法名/入参的类名首字母组合”。
如果@BridgeOperation定义的方法没有入参，那么path路径中则没有“入参的类首字母组合”；如果两个同名方法入参的类名首字母组合相同，那么第二个及之后的同名方法的path路径会追加“/index数字”以区分不同的方法，index的排序以springfox-bridge内部对方法加载的顺序进行排序。
@BridgeOperation注解的value值标识该方法的简要说明，跟path在同一行展示。
@BridgeModelProperty注解可以对方法入参进行标识，用以对入参加以说明
方法入参类型如果是一个model类，该model类可以用io.swagger包的原生注解@ApiModel（标识类）和@ApiModelProperty（标识字段）对model类进行说明，之所以用原生注解，是为了兼容原生springfox，不必重复定义注解。
在swagger界面上可以看到，springfox-bridge对每个标识了@BridgeOperation的方法都动态生成一个post请求，并动态生成一个body请求体，方法的所有入参都作为新请求体的字段。

四、springfox-bridge注解说明

4.1 springfox-bridge自定义注解

注解	位置	主要字段	说明	对标原生注解
BridgeApi	类	description	对类进行说明	io.swagger.annotations.Api
BridgeGroup	类	value	标识分组	无
BridgeOperation	方法	value、notes	value、notes分别标识方法概要和详细说明	io.swagger.annotations.ApiOperation
BridgeModelProperty	入参	value	标识入参说明	io.swagger.annotations.ApiModelProperty

4.2 兼容的springfox swagger原生注解

目前兼容入参的请求体的model用io.swagger包的原生注解@ApiModel、@ApiModelProperty ，后续会提供其它支持

五、展望

目前springfox-bridge的1.0.3版本已经发布到maven*仓库，后续会更新支持更多的特性, 比如：兼容更多的springfox swagger的原生注解、支持返回体说明、支持author自定义、支持入参类型全名展示等。项目源码见github： https://github.com/double-bin/springfox-bridge

码农公寓