swagger介绍

• Swagger是什么？
• 自动文档的好处？
• 自动化文档开发的初衷

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