- 小知识，大挑战！本文正在参与“程序员必备小知识”创作活动。
Swagger
一、描述
现代化的研发组织架构中，一个研发团队基本包括了 产品组、后端组、前端组、APP端研发、 测试组、 UI 组等，各个细分组织人员各司其职，共同完成产品的全周期工作。如何进行组织架构内的有效高效沟通就显得尤其重要。其中，如何构建一份合理高效的接口文档更显重要。 随着互联网技术的发展，现在的网站架构基本都由原来的后端变成前后端分离。前后端的唯一联系，是通过API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要。
二、API文档
解决方案：手写文档完成前后端开发。
开发文档手册：
手写文档存在的问题
- 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
- 接口返回结果不明确
- 不能直接在线测试接口，通常需要使用工具，比如：
Postman - 接口文档太多，不好进行维护管理
- 文档是接口提供方手动导入的，是静态文档，没有提供接口测试功能
三、 Swagger
1、简介
官网：swagger.io/ Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。 Swagger 也就是为了解决这个问题，当然也不能说 Swagger 就一定是完美的，当然也有缺点，最明显的就是代码植入性比较强。
作用：
-
接口的文档在线自动生成。
-
功能测试。
2、Swagger组件
Swagger是一组开源项目，其中主要要项目如下：
- Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
- Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。
- Swagger-js: 用于JavaScript的Swagger实现。
- Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
- Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
- Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。
3、Swagger集成
1.增加 Swagger2 所需依赖
2创建Swagger2配置类
1 、类描述
@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
2、 方法描述
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用" notes="方法的备注说明"
3、方法参数描述
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
defaultValue：参数的默认值
4、方法响应参数
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400 message：信息，例如"请求参数没填好" response：抛出异常的类
