SwaggerUI--SosoApi-阿里云开发者社区

开发者社区> 开发与运维> 正文
登录阅读全文

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?         现在多数的项目开发中,网站和移动端都需要进行数据交互和对接,这少不了使用REST编写API接口这种场景。

 

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?


        现在多数的项目开发中,网站和移动端都需要进行数据交互和对接,这少不了使用REST编写API接口这种场景。 特别是不同开发小组协作时,就更需要以规范和文档作为标准和协作基础。良好的文档可以减少沟通成本,达到事半功倍的效果。

        有时对一些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弊端?


集成方式

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

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

 

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


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

 

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

 

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
开发与运维
使用钉钉扫一扫加入圈子
+ 订阅

集结各类场景实战经验,助你开发运维畅行无忧

其他文章
最新文章
相关文章