springfox源码_【开源项目】springfox-bridge：随心所欲地为非restful接口生成API文档...

一、引言

目前，利用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文档的能力。

二、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的项目：

com.github.double-bin

springfox-bridge-spring-boot-starter

1.0.8

非springboot项目：

com.github.double-bin

springfox-bridge-core

1.0.8

3.2 启动配置

1)使用了springboot的项目

配置了springfox-bridge-spring-boot-starter后，默认开启springfox-bridge。

如果需要关闭，可以在application.properties文件(或yml文件)中配置springfox.bridge.enabled的值为false即可

非springboot项目：

可通过配置类实现ApplicationContextAware接口的setApplicationContext方法，方法实现中通过SpringfoxBridge.