Springfox与swagger的整合使用

1、前言

让咱们先理一下springfox与swagger的关系。

swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，对整个API的开发周期都提供了相应的解决方案，是一个很是庞大的项目（包括设计、编码和测试，几乎支持全部语言）。

OAS自己是一个API规范，它用于描述一整套API接口，包括一个接口是GET仍是POST请求啊，有哪些参数哪些header啊，都会被包括在这个文件中。它在设计的时候一般是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多，由于json的通用性比较强。

因为Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来，同时springfox也是一个新的项目，本文仍然是使用其中的一个组件springfox-swagger2。

pringfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助咱们自动生成这个json文件，咱们会用到的另一个组件springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来。

这是入门，咱们简单地介绍springfox-swagger2的配置，帮助各位顺利地实现使用，文中有不少本身的理解，如有错误，欢迎批评指正。

2、配置流程说明

在开始编码以前，咱们先对配置的流程有个大体的了解。

在前言中，咱们知道，咱们的第一个任务就是生成一个知足OSA规范的json文件（固然，建立一个spring的项目就不说了）。对于这个任务，springfox为咱们提供了一个Docket（摘要的意思）类，咱们须要把它作成一个Bean注入到spring中，显然，咱们须要一个配置文件，并经过一种方式（显然它会是一个注解）告诉程序，这是一个Swagger配置文件。

一个OSA规范文档须要许多信息来描述这个API，springfox容许咱们将信息组合成一个ApiInfo的类，做为构造参数传给Docket（固然也能够不构造这个类，而直接使用null，可是你的这个API就太low了）。

接下来，咱们要写控制器了，固然这不重要，不用springfox你依然要写控制器，重要的是要告诉springfox，这个控制器是一个须要他来收集API信息的控制器，不用说，这依然会采用注解的方式，同时，咱们为了将配置文件与控制器结合起来，须要在配置文件中指明在什么位置收集多是API的控制器的信息。

到这里，生成OSA规范的json文件的配置就结束了。虽然生成过程比我叙述的更复杂，但这些程序都会帮咱们完成，咱们能够经过相似http://localhost:8080/demo/v2/api-docs的路径来查看这个json文件。这个v2/api-docs就是springfox默认的生成文档的路径。

接下来，咱们须要将它可视化显示出来，若是使用swagger-springmvc，咱们须要单独去下载一个swagger ui的显示页面包，并将其中的路径改成上面的http://localhost:8080/demo/v2/api-docs，这里你就能够感觉到，swagger ui就是在解析一个json文件了。你依然能够这么作，不过springfox专门提供了一个springfox-swagger-ui组件，不须要配置，咱们只须要引入这个依赖的组件就能够看到最终的效果了，而这个路由会是http://localhost:8080/demo/swagger-ui.html。

3、引入依赖

若是我写的不错，相信看到这里，你就大体了解了springfox swagger2的使用流程了。那么，咱们进入正式编码的第一步：引入依赖。

这里咱们使用maven引入依赖，你们能够到http://mvnrepository.com上搜索springfox，即可以看到Springfox Swagger2和Springfox Swagger Ui，而后就能够从中获取最新的资源了。以下：

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.7.0</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.7.0</version>

</dependency>

 

此外还须要一个依赖组件：

<dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.6.6</version>
</dependency>

 

4、一个简单的配置文件

为了清晰，咱们能够先在经常使用的源码包里建一个config目录，并在里面建立一个SwaggerConfig.java文件，这是一个spring的配置文件，因此位置和文件名都影响不大。

先上代码（这里参考了博客http://blog.csdn.net/u012476983/article/details/54090423）：

@Configuration //必须存在
@EnableSwagger2 //必须存在
@EnableWebMvc //必须存在
@ComponentScan(basePackages = {"com.xiaoming.SpringMVC.controller"}) //必须存在 扫描的API Controller package name 也能够直接扫描class (basePackageClasses)
public class SwaggerConfig{
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("小明", "http://www.cnblogs.com/getupmorning/", "zhaoming0018@126.com");
        return new ApiInfoBuilder()
                .title("前台API接口")
                .description("前台API接口")
                .contact(contact)
                .version("1.1.0")
                .build();
    }
}

 

因为各位确定用的是IDE，这里就不写各类import了。

首先，这个SwaggerConfig类有四个注解，看名称就能够明白是什么意思。其中，@Configuration，@EnableWebMvc和@ComponentScan是Spring的注解，而@EnableSwagger2则是用来启动Swagger支持，表示这是一个Spring Swagger的配置文件。

以后，定义了一个Bean方法CustomDocket，Spring中名字并不重要，重要的是它返回一个Docket类，DocumentationType.SWAGGER_2做为Docket构造方法的参数，指定了所用的swagger版本2.0，官网上已经在预告3.0版本了。而以后的apiInfo则是调用接下来的apiInfo函数，来建立Docket的信息。apiInfo函数采用ApiInfoBuilder来建立ApiInfo类。

5、一个控制器

其实，控制器不须要配置，就已经会被springfox swagger识别了，不过咱们这里象征性地加上一个描述信息：

@Controller
@RequestMapping("/test")
public class TestController {
    @ApiOperation(value="一个测试API",notes = "第一个测试api")
    @ResponseBody
    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    public String hello()
    {
        return "hello";
    }
}

 

这里仅仅多了一个@ApiOperation注解，别的和一个普通的springmvc的控制器彻底一致。

实际上，为了造成一个完整的api文档，须要添加的注解经常不少，如果都写在同一个文件里就会显得臃肿，咱们经常会写一个接口文件，将注解都放在接口文件中，而后再用一个实体类来实现控制器，算是实现配置和逻辑分离了吧。

6、查看接口文件和文档

如果没有问题，如今能够部署项目，并打开http://localhost:8080/demo/v2/api-docs：

 

 

Firefox提供了查看JSON的插件，推荐你们搜索试试看。

废话很少说，这里能够看到以前配置的诸多信息。注入description，version，title等。而且确实有TestController的信息。

最后，咱们打开http://localhost:8080/swagger-ui.html，即可以看到一个漂亮的界面了：