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; ...
重新运行起项目，访问效果如下：
