Swagger介绍

Swagger是一种REST APIs的简单但强大的表示方式，标准的，语言无关，这种表示方式不但人可读，而且机器可读。可以作为REST APIs的交互式文档，也可以作为REST APIs的形式化的接口描述，生成客户端和服务端的代码。
官网
 GitHub - swagger-api/swagger-ui)
GitHub - swagger-api/swagger-editor: Swagger Editor
GitHub - Swagger2Markup/swagger2markup: Swagger2Markup

1. 前言

在没有产品经理或者项目经理的情况下，对于前端和后端打交道来说，无非就是对接口的争争吵吵，字段多多少少的事。大多时候前端都喜欢直接使用后端提供的接口，而后端有时候却不知道前端到底要什么数据，就这样，Swagger这样的神器被我找到了，对于Swagger高级的应用，比如集成到IDE中自动生成文档,支持GO/python/Java等多种语言的IDE集成环境!

2. Swagger UI和Swagger Editor

swagger ui是一个API在线文档生成和测试的利器,目前发现最好用的。

支持API自动生成同步的在线文档
这些文档可用于项目内部API审核
方便测试人员了解API
这些文档可作为客户产品文档的一部分进行发布
支持API规范生成代码，生成的客户端和服务器端骨架代码可以加速开发和测试速度

使用Swagger Editor编写API文档

Swagger Editor上的是基于yaml/JSON的语法

3. 为什么选择Swagger

使用Swagger UI生成的界面比Javadoc生成的界面美观
swagger可以实时同步API文档(代码修改后，文档同步修改)
swagger解析速度快，效率高(使用轻量级数据交换格式JSON)
对现有SpringMVC工程支持友好
Swagger可以充当前后端交流的重要桥梁，方便快捷。很实用。
Swagger项目允许你生产，显示和消费你自己的RESTful服务。不需要代理和第三方服务。是一个依赖自由的资源集合，它能通过Swagger-API动态的生成漂亮的文档和沙盒,因为Swagger-UI没有依赖，你可以把他部署到任何服务器环境或者是你自己的机器

4. Swagger组件介绍

部署安装略,可自行在github中查找,建议使用Docker方式安装部署,简单方便;
Swagger生态工具组件较多,本文主要介绍Swagger-Editor以及Swagger-UI的使用,Editor用于生成各语言客户端/服务端的依赖文件,UI部分主要针对客户端工具生成的swagger.json或swagger.yml文件进行接口的查看和接口测试;
Swagger也有支持生成MarkDown文档格式的组件(Swagger2Markup);
PS: Swgger UI的站点域名要和发送请求的域名一样,不然浏览器会报跨域错误。
示例Demo
Swagger Editor
Swagger UI