SpringMVC集成springfox-swagger2自动生成接口文档

本节内容：

什么是Swaggger
Springfox与Swagger的关系
SpringMVC集成springfox-swagger2

一、什么是Swaggger

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

二、Springfox与Swagger的关系

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

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

如果想要集成swagger-springmvc就相对麻烦一点，因为要把它的静态文件copy到自己的项目中。springfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件，我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来。

三、SpringMVC集成springfox-swagger2

1. 添加依赖的jar包

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

2. spring-mvc.xml中添加映射静态的配置

<mvc:default-servlet-handler />

3. 配置文件

在源码包里建一个config目录，并在里面创建一个SwaggerConfig.java文件，这是一个spring的配置文件，所以位置和文件名都影响不大。

SwaggerConfig.java

package com.spring.learn.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;

/**
 * Created by jkzhao on 1/19/18.
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.spring.learn.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring 中使用Swagger2构建RESTful APIs")
                .termsOfServiceUrl("http://www.cnblogs.com/zhaojiankai/")
                .description("springmvc swagger2")
                .contact(new Contact("zhaojiankai", "http://www.cnblogs.com/zhaojiankai/", "743833196@qq.com"))
                .version("1.1")
                .build();
    }
}

这个SwaggerConfig类有四个注解，其中，@Configuration是Spring的注解，而@EnableSwagger2则是用来启动Swagger支持，表示这是一个Spring Swagger的配置文件。

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

然后运行项目，在浏览器输入：http://{ip}:{port}/{projectname}/swagger-ui.html

它会把按照controller，把所有的接口都加载进来。

我的目录结构如图：

然后，就是接口名称和参数的说明：
常用注解：

@Api()用于类名
@ApiOperation()用于方法名
@ApiParam()用于参数说明
@ApiModel()用于实体类
@ApiModelProperty用于实体类属性

更详细的说明请参见官方注解说明文档

【示例】：

ApiController.java

@Controller
@RequestMapping("/api")
@Api(value = "api接口", description="用户相关操作")
public class ApiController {
    @Autowired
    private UserService userService;

    @RequestMapping(value = "/user", method = {RequestMethod.GET})
    @ApiOperation(value = "用户查询服务", notes = "根据传过来的user_id来查询用户")
    public String getUserById(@ApiParam(value = "用户id") String user_id, ModelMap map){
        User user =  userService.getUserById(user_id);
        map.put("user", user);

        return "success";
    }

}

User.java

@ApiModel(value = "用户")
public class User {
    private String user_id;

    @ApiModelProperty(value = "用户名")
    private String user_name;

    @ApiModelProperty(value = "密码")
    private String password;
    ...

重新运行起项目，访问效果如下：