SwaggerUI--SosoApi

​​1、SwaggerUI是什么？​​

Swagger UI是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

Swagger-UI 的官方地址：​​http://swagger.io/​​

Github上的项目地址： ​​https://github.com/swagger-api/swagger-ui​​

官方提供的demo地址：​​http://petstore.swagger.io/​​

​​2、为什么API接口文档用SwaggerUI？​​

协作基础。良好的文档可以减少沟通成本，达到事半功倍的效果。

        有时对一些API说明的理解比较模糊，总想着能直接验证一下自己的理解就好了，而不是需要去项目写测试代码来验证自己的想法。 即API文档应具备直接执行能力，这种能力类似word,wiki等是无法提供。 SwaggerUI就是这样一种利器，基于html+javascript实现，倾向于在线文档和测试，使用和集成十分简单，能容易地生成不同模块下的API列表， 每个API接口描述和参数、请求方法都能定制并直接测试得到直观的响应数据。

        体验SwaggerUI最好的方法就是看下官网提供的demo，看过之后相信你一定会兴奋不已。

​​3、SwaggerUI怎么用？​​

目前官方提供的SwaggerUI的使用方式主要有2种：

与不同的服务端代码集成 在服务端代码中嵌入SwaggerUI文档生成代码，部署时自动生成。   手动编辑对应的json文档 该json文档有其特定格式，相对比较复杂，手动编写难度比较大，可通过官方提供的​​在线编辑​​来实现。

​​4、SwaggerUI有什么弊端？​​

集成方式

侵入性比较大，将文档参数和应用参数杂糅在一起，不易阅读，而且比较依赖于项目， 无法独立部署，项目挂掉，文档也无法访问。给后期代码维护增加难度。

        如果直接编辑json文档，则难度比较大，即使是官网的在线编辑功能也比较弱，提示功能差劲，很多时候在编辑预览中没问题，导出来部署就显示不正常，而且 不支持多人编辑，只能一次一个人改，部署相当不方便。

  用户体验         无论请求还是响应无法方便的输入自定义json格式，特别是多层嵌套，异常繁琐。

​​5、SosoApi如何解决SwaggerUI弊端？​​

集成方式

推荐编辑json文档。 不过，将编辑方式变更为表单提交方式，用户只要动动鼠标，敲敲几个关键字就可以输出一个接口， 方便快捷，而且无需学习SwaggerUI相关的json格式，上手简单，减少学习成本。

  用户体验         SosoApi支持自定义json格式，可以随意的输入自定义的json，再也不用受到原来文档格式的约束。

​​6、扩展版SwaggerUI新增了哪些功能？​​

• 请求参数数据类型新增"自定义"，允许用户直接输入相关的json格式数据
• 响应数据类型新增"自定义"，允许用户直接输入相关的json格式数据
• 国际化支持
• bug修复

​​http://www.sosoapi.com/pass/faq/swagger.htm​​