开发文档的弊端

        随着软件开发的分工明确化，前后端分离成为越来越流行的一种开发形式，这样可以更好的提高开发效率和项目进度。可是在开发web项目时，因为需求变动等原因，免不了要修改后台代码，可能是修改了方法签名（方法名和参数列表）,可能是新增或者删除了方法,结果开发文档忘记更新了，前端开发时，看着错误的文档开发，发现接口参数不对，或者接口不存在，然后就噼里啪啦的各种问，结果才发现，原来罪魁祸首是忘记更新开发文档。而且，多次修改开发文档，自己也不知道哪一个是最新的了。此时，你会问可以不写开发文档还能保证接口的实时性与准确性吗？答案是可以的,为解决开发人员的痛点，swagger  UI应运而生。

认识Swagger

        那么Swagger到底是什么玩意？又能干什么？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

 作用：接口的文档在线自动生成 ；功能测试。

说白了就是：1.实时更新API文档    2.提供功能测试（post方法不用再使用postman测试了，这个还是非常方便的）

如何使用Swagger

        废话不多说，先上代码，任何框架，不都得先学会用再去了解原理的，哪个方法不是从helloWorld开始的，如果不是，那就是N个helloWorld。

1.在pom.xml里面添加swagger 的maven依赖

        <!-- swagger2 依赖开始 -->
        <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>
        <!-- swagger2 依赖结束 -->

2. 添加Swagger的配置类

/**
 * @author Tyler.Shi
 * @date 2018/8/24
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，
     * 比如扫描的包等等
     * @return docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径 ,扫描controller包
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
// 含有RestController的注解
// .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
// 含有api的注解
// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("tyler.shi", "http://www.baidu.com", ""))
                //版本号
                .version("1.0")
                //描述
                .description("first demo for swagger")
                .build();
    }

}

3. 配置Swagger跳转主页

/**
 * @author Tyler.Shi
 * @date 2018/8/24
 */
@Controller
@RequestMapping(value = {"/home", "/"})
public class HomeController {

    @GetMapping(value = {"/", "api"})
    public String helloWorld() {
        return "redirect:/swagger-ui.html";
    }
}

4.  以上步骤完成了，就可以启动项目了，如果没有配置启动端口，那么默认的就是8080，浏览器输入localhost:8080就会跳转到主页

5. 到这一步你已经完成Swagger的基本配置和使用了，为了让Swagger UI文档更具可读性（让前端开发人员一看就懂），下面我们来介绍一下Swagger的几个常用注解

 @Api()用于类:表示标识这个类是swagger的资源  里面可选的 注释有value ，description,tags,其中tags是用来归类的，具有相同值的tags会在API页面中放在一起

@ApiOperation()用于方法: 表示一个http请求的操作

@ApiParam()用于方法、参数、字段说明：表示对参数的添加

其中defaultValue为默认值，不传值时默认为helloWorld;   allowableValues为可选值，如果参数为枚举，可以考虑使用

@ApiModelProperty()用于方法、字段：表示对model属性的说明或者数据操作更改 

/**
 * @author Tyler.Shi
 * @date 2018/8/28
 */
@Data
public class User {

    @ApiModelProperty(value = "10")
    private Integer id;
    @ApiModelProperty(value = "LiMei")
    private String name;
    @ApiModelProperty(value = "20")
    private Integer age;
    @ApiModelProperty(value = "10086")
    private String phone;
}

这里就介绍一下常用的几个注解吧，还有好多其他的注解这里就不介绍了，感兴趣的小伙伴自行找资料学习。