前两天提到项目组打算用 swagger 来做为 RESTful API 的解决方案，现在已经确定下来了。
之前看到有文章介绍 SpringBoot 中结合 Swagger 直接生成文档的方法，今天尝试了一下，入门还是比较简单的。
项目组最近新开发一套 RESTful API，需要对应的 API 文档，其实之前我有用 apidoc 作为方案给大家看过。
感觉还好，也是可以直接写成注释放在代码里最后生成。但能感受到它属于轻量级的，内容相对自由，灵活度很大，但也意味着更容易犯错。
不过最后上面还是决定使用 swagger 这一套东西，所以简单的看了下，功能果然成强大，显得更 professionnal 一些。
下面就罗列下我目前掌握的一些信息，其实学习 swagger 的过程就是学习 RESTful API 的过程。
针对RESTful API,有许多工具可以用来编写文档比如Swagger2，之前发现一个挺好用的库就是apidocjs
这个库支持大多数流行程序语言，把接口相关的信息放在注释中，而这个js库解析注释中的有效信息生成html文档，需要安装node.js。
REST 全称是 Representational State Transfer，中文意思是表述性状态转移。 它首次出现在 2000 年 Roy Fielding 的博士论文中，Roy Fielding 是 HTTP 规范的主要编写者之一。 他在论文中提到：”我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。REST 指的是一组架构约束条件和原则。” 如果一个架构符合 REST 的约束条件和原则，我们就称它为 RESTful 架构。
REST 本身并没有创造新的技术、组件或服务，而隐藏在 RESTful 背后的理念就是使用 Web 的现有特征和能力， 更好地使用现有 Web 标准中的一些准则和约束。虽然 REST 本身受 Web 技术的影响很深， 但是理论上 REST 架构风格并不是绑定在 HTTP 上，只不过目前 HTTP 是唯一与 REST 相关的实例。 所以我们这里描述的 REST 也是通过 HTTP 实现的 REST。