swagger介绍

版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
本文链接:https://blog.csdn.net/qq_21794823/article/details/78194164

Swagger是什么?

Swagger 是一个规范和一套完整的框架,用于生成、描述、调用以及可视化 RESTful 风格的 Web 服务。

Swagger的总体目标是使客户端和文件系统服务器以同样的速度来更新,方法,参数和模型紧密集成到服务器端的代码中,允许API始终保持同步。

Swagger 让部署管理和使用API从未如此简单。

Swagger包括库、编辑器、代码生成器等很多部分,这里我们主要讲一下Swagger Editor。这是一个完全开源的项目,并且它也是一个基于Angular的成功案例,我们可以下载源码并自己部署它,也可以修改它或集成到我们自己的软件中。

在Swagger Editor中,我们可以基于YAML语法定义我们的RESTful API,然后它会自动生成一篇排版优美的API文档,并且提供实时预览。相信大多数朋友都遇到过这样一个场景:明明调用的是之前约定好的API,拿到的结果却不是想要的。

可能因为是有人修改了API的接口,却忘了更新文档;或者是文档更新的不及时;又或者是文档写的有歧义,大家的理解各不相同。总之,让API文档总是与API定义同步更新,是一件非常有价值的事。

自动文档的好处?

1. 不用手动写文档了,通过注解就可以自动化文档

2. 文档和代码同步更新,代码更新之后不需要再更新文档

3. 浏览器友好

4. 使用Swagger框架可以调试API,在浏览器端可以看到更多的`request`和`response`信息

自动化文档开发的初衷

我们需要开发一个API应用,然后需要和手机组的开发人员一起合作,当然我们首先想到的是文档先行,我们也根据之前的经验写了我们需要的API原型文档,我们还是根据github的文档格式写了一些漂亮的文档,但是我们开始担心这个文档如果两边不同步怎么办?因为毕竟是原型文档,变动是必不可少的。手机组有一个同事之前在雅虎工作过,他推荐我看一个swagger的应用,看了swagger的标准和文档化的要求,感觉太棒了,这个简直就是神器啊,通过swagger可以方便的查看API的文档,同时使用API的用户可以直接通过swagger进行请求和获取结果。所以我就开始学习swagger的标准,同时开始进行Go源码的研究,通过Go里面的AST进行源码分析,针对comments解析,然后生成swagger标准的json格式,这样最后就可以和swagger完美结合了。

这样做的好处有三个:

  1. 注释标准化
  2. 有了注释之后,以后API代码维护相当方便
  3. 根据注释自动化生成文档,方便调用的用户查看和测试


参考链接:http://www.cnblogs.com/whitewolf/p/4686154.html

                  http://www.cnblogs.com/huligong1234/p/4707282.html

                  http://www.thinksaas.cn/topics/0/585/585305.html

展开阅读全文

没有更多推荐了,返回首页