本节内容：

• 什么是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包

     
         
      
       io.springfox
          
      
       springfox-swagger2
          
      
       2.6.1
      
     
         
      
       io.springfox
          
      
       springfox-swagger-ui
          
      
       2.6.1
      
     

　　

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

 

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@Configurationpublic 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;    ...

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