如何使用swagger生成接口文档（推荐一款API神器Swagger）

现在的网站架构基本上都是前后端分离，然后出现了前端工程师和后端工程师的岗位区分(当然你也可以是全栈的)。前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要

相信大多数朋友都遇到过上面的场景：明明调用的是之前约定好的API，拿到的结果却不是想要的。可能因为是有人修改了API的接口，却忘了更新文档；又或者是文档写的有歧义，大家的理解各不相同。

一般软件开发项目组都会有API文档，它是前后端开发人员配合工作的桥梁。常规文档的形式都是记录在word或者是类似confluence的wiki服务器上。但是这些形式都会出现上面的问题。让API文档总是与API定义同步更新，是一件非常有价值的事。

于是今天我来介绍一款API神器（Swagger）。Swagger号称是最好的API工具。官方网站 https://swagger.io/

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger作用：1. 在线自动生成排版优美的接口文档。2. 功能测试。

鉴于swagger的强大功能，Java开源界大牛spring框架迅速跟上，它充分利用自已的优势，把swagger集成到自己的项目里，整了一个spring-swagger，后来便演变成springfox。springfox本身只是利用自身的aop的特点，通过plug的方式把swagger集成了进来，它本身对业务api的生成，还是依靠swagger来实现。

maven依赖：

=>@EnableSwagger2注解,启动Swagger支持，表示这是一个Spring Swagger的配置文件

=>@Api表示这是一个需要Swagger表示的类写在Controller的头部

@ApiOperaction表示这是一个需要Swagger修饰的接口，其中表明了接口名称，请求方式、备注说明等信息。

@ApiImplicitParam表示该接口输入的参数：name表示参数名称；value表示参数说明；paramType表示传入类型，请求头传入写query,JSON类型传入写json；defaultValue表示默认值；required表示参数是否必须传。

项目启动后就可以直接用类似于以下的地址来查看api列表了：http://127.0.0.1:8080/jadDemo/swagger-ui.html

是不是很不错，try it！