作者：方雷
个人博客：http://blog.chargingbunk.cn/
微信公众号：rayson_666(Rayson开发分享)
个人专研技术方向：

• 微服务方向：springboot, springCloud, Dubbo
• 分布式/高并发： 分布式锁， 消息队列RabbitMQ
• 大数据处理： Hadoop, spark, HBase等
• python方向： python web开发

喜欢的朋友们可以关注我的简书或微信公众号(rayson_666), 一起交流学习， 后期会不断更新有经验的干货.

一，前言

这两天有新项目即将开工，目前采用前后端分离的模式开发，我也是第一次进行这样的模式，但是公司有没有很有经验的大佬指点， 之前就靠自己在网上查阅大量的资料，搭建起了springboot+Dubbo+zookeeper的基本框架， 并采用了Maven的多模块开发，也是踩过很多的坑，不过沉淀下来的确是满满的经验和教训。目前这一套基础框架也已经使用到生产环境当中。现在的项目也是基于maven的多模块开发， 一步一步的搭建起满足项目需求的脚手架， 方便以后可以更快速的开发新的项目。

前后端分离， 就是后端只负责提供前端的接口，为了减少与前端的沟通成本， 可以更直观，快速地与前端人员进行接口对接， 就少不了接口文档， 而目前最流行地接口文档插件就是swagger， 目前使用Swagger2版本。

我这两天就在负责搭建Swagger2， 即便网上有很多这方面的教程， 但是都比较零散， 使得我在搭建过程中， 总是会出现很多莫名奇妙的问题， 出现这些问题的地方， 也没有一篇好的总结。所以我把自己在项目中遇到的情况及解决方案记录下来， 如果我们遇到同样的情况， 也方便查阅。

二， 开始

1.引入Swagger依赖

在pom.xml中引入 springfox-swagger2 和 springfox-swagger2-ui

<!-- 构建Restful Api文档 -->
<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>

2. 创建Swagger2配置类

参考网上的配置，根据实际项目修改一下就可以了。

package cn.rayson.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 
 * Swagger2配置类
 * @author 方雷(Rayson)
 * @微信公众号: rayson_666(Rayson开发分享) 、
 * 分享springBoot springCloud技术, 以及python,大数据学习系列
 * @个人博客: http://blog.chargingbunk.cn/
 * @简书: https://www.jianshu.com/u/5b0de5c8dc56
 * 2018年6月9日
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
   //swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket defaultApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("默认分组").select()
                .apis(RequestHandlerSelectors.basePackage("cn.rayson.controller")).paths(PathSelectors.any()).build();
    }

    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    // 预览地址:swagger-ui.html
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("利用swagger构建测试系统api文档")
                .description("接口访问地址：http://localhost:8080/, by 方雷")
                .termsOfServiceUrl("http://localhost:8080/")
                //.contact("方雷")
                .version("1.0")
                .build();
    }
}

如上代码所示， 通过@Configuration注解， 让springboot来加载该类的配置。在通过@EnableSwagger2注解来启用Swagger2。

再通过@Bean注入Docket实体类， apiInfo()用来创建该api的基本信息，这些信息将会展现在文档页面中。

select() 函数会返回一个ApiSelectorBuilder实例，用来控制哪些接口暴露到swagger页面中。 本例采用指定包路径来定义， Swagger会扫描该包下的所有Controller定义的api, 并生成文档展现在swagger页面中（除了接口被@ApiIgnore指定的会被忽略）

3. 编写Controller并进行Restful接口文档测试

在Swagger2配置的包扫描路径下， 新建一个Controller

package cn.rayson.controller;
import java.util.HashMap;
import java.util.Map;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

@Api(value="测试api", tags="测试api")
@RestController
public class RestTestController {
    
    @ApiOperation(value="获取信息", notes="根据url的id来获取信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true)
    @RequestMapping("/test")
    @ResponseBody
    public Object index(Integer id){
        Map map = new HashMap();
        map.put("name", "test");
        map.put("age", 13);
        return map;
    }   
}

具体注解什么意思，可以自行百度，我们的目的是能成功访问到swagger页面，至于以后再慢慢了解。

4. 运行成功后的Swagger效果

image.png

5. 最后来看看Swagger2的常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

三，总结

以上就是SpringBoot整合Swagger2的整体过程，也是我们百度搜索出现基本上已经算是烂大街，随便一搜就可以找到。我为什么又要写呢？当然是保证整个知识的完整性， 为接下来要分享的踩坑并填坑做铺垫，为以后的项目开发中少走弯路。