springfox源码_springfox-swagger原理解析与使用过程中遇到的坑

swagger简介

swagger确实是个好东西，可以跟据业务代码自动生成相关的api接口文档，尤其用于restful风格中的项目，开发人员几乎可以不用专门去维护rest

api，这个框架可以自动为你的业务代码生成restfut风格的api，而且还提供相应的测试界面，自动显示json格式的响应。大大方便了后台开发人员与前端的沟通与联调成本。

springfox-swagger简介

签于swagger的强大功能，java开源界大牛spring框架迅速跟上，它充分利用自已的优势，把swagger集成到自己的项目里，整了一个spring-swagger，后来便演变成springfox。springfox本身只是利用自身的aop的特点，通过plug的方式把swagger集成了进来，它本身对业务api的生成，还是依靠swagger来实现。

关于这个框架的文档，网上的资料比较少，大部分是入门级的简单使用。本人在集成这个框架到自己项目的过程中，遇到了不少坑，为了解决这些坑，我不得不扒开它的源码来看个究竟。此文，就是记述本人在使用springfox过程中对springfox的一些理解以及需要注意的地方。

springfox大致原理

springfox的大致原理就是，在项目启动的过种中，spring上下文在初始化的过程，框架自动跟据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能需要生成api文档那些类，并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类，跟据这些Controller类中的方法生成相应的api文档。

因本人的项目就是SpringMvc，所以此文就以Srping

mvc集成springfox为例来讨论springfox的使用与原理。

SpringMvc集成springfox的步骤

首先，项目需要加入以下三个依赖：

org.springframework

spring-webmvc

4.2.8.RELEASE

io.springfox

springfox-swagger2

2.6.1

io.springfox

springfox-swagger-ui

2.6.1

上面三个依赖是项目集成springmvc及springfox最基本的依赖，其它的依赖这里省略。其中第一个是springmvc的基本依赖，第二个是swagger依赖，第三个是界面相关的依赖，这个不是必须的，如果你不想用springfox自带的api界面的话，也可以不用这个，而另外自己写一套适合自己项目的界面。加入这几个依赖后，系统后会自动加入一些跟springfox及swagger相关jar包，我粗略看了一下，主要有以下这么几个：

springfox-swagger2-2.6.1.jar

swagger-annotations-1.5.10.jar

swagger-models-1.5.10.jar

springfox-spi-2.6.1.jar

springfox-core-2.6.1.jar

springfox-schema-2.6.1.jar

springfox-swagger-common-2.6.1.jar

springfox-spring-web-2.6.1.jar

guava-17.0.jar

spring-plugin-core-1.2.0.RELEASE.jar

spring-plug-metadata-1.2.0.RELEASE.jar

spring-swagger-ui-2.6.1.jar

jackson-databind-2.2.3.jar

jackson-annotations-2.2.3.jar

上面是我通过目测觉得springfox可能需要的jar，可能没有完全例出springfox所需的所有jar。从上面jar可以看出pringfox除了依赖swagger之外，它还需要guava、spring-plug、jackson等依赖包(注意jackson是用于生成json必须的jar包，如果项目里本身没有加入这个依赖，为了集成swagger的话必须额外再加入这个依赖)。

springfox的简单使用

如果只用springfox的默认的配置的话，与springmvc集成起来非常简单，只要写一个类似于以下代码的类放到你的项目里就行了，代码如下：

@Configuration

@EnableWebMvc

@EnableSwagger2

publicclassApiConfig {

}

注意到，上面是一个空的java类文件，类名可以随意指定，但必须加入上述类中标出的@Configuration、@EnableWebMvc、@EnableSwagger2三个注解，这样就完成了springmvc与springfox的基本集成，有了三个注解，项目启动后就可以直接用类似于以下的地址来查看api列表了：

http://127.0.0.1:8080/jadDemo/swagge