开篇首先给出结论，目前tornado与swagger的集成程度并不高，如果想要通过swagger自动生成API，需要对其进行深度定制，下面给出调研的一些结果

商业项目中，随着迭代的速度越来越快，与之相应的文档维护变得越发麻烦。 久而久之，项目文档与当前项目代码版本差的越来越远，便失去了其价值

本地调研的目的是找到一种能够高效维护API文档的解决方案。

一个项目中，文档是不可或缺的组成部分，其中比较重要的有：

好的文档可以：

当然写文档也有“坏处”，那就是费时费力，如果文档不及时更新，甚至会给后来接手项目的人造成不必要的困扰。 总的来说，文档是一定要写的，那么问题就转变为：如果高效的编写和维护文档

Confluence是一个企业级的Wiki软件，可用于在企业、部门、团队内部进行信息共享和协同编辑。

说了是Wiki软件，那么基本是什么文档都可以往上面放，接口文档自然不在话下，并且能够团队协同编辑，内置的富文本编辑器也是十分的好用，谁用谁知道～

关键是上手完全没有任何难度，如果目前还没有使用类似的文档管理系统，那么confluence非常值得一试

这里就不多详细描述了，网上教程很多，贴一个博客链接，有兴趣的可以自己摸索一下

But，尽管confluence很好用，它仍然没有解决文档维护困难的问题，你还是要手动在编辑器上自己写文档。

当我看到Ray的时候，这个工具已经出到2了，由于老版本的ray已经不在维护，所以这里就直接介绍Ray2

Ray2相较于confluence，其功能更加的专一，它就是一个专门用来管理API接口文档的平台

首先，Ray2是开源的，由阿里妈妈前端团队维护（阿里出品，必属精品～）

这是Ray2的github地址

同样的上手非常简单，并且可以无需安装直接体验，地址就在上面github的README下面

简单来看一下界面 从概念上来讲，Ray2提供了仓库–>模块–>接口的层级，一个个仓库就相当于项目，每个项目又按模块进行划分，而模块下面的自然就是一个个接口文档了。

从编写方式来讲，Ray2提供了非常高效的API文档模版，我们只需要往模版里面填写数据，就可以快速编写API接口文档，这相较于在confluence下一个字一个字的码，无疑更进了一步。

使用Ray2维护API文档已经十分高效了，但是归根结底，还是需要人去手动维护的，那么有没有更加强大，便捷的文档维护方式呢，答案是YES，就是下面即将介绍的 Swagger

Swagger是一种Rest API的 简单但强大的表示方式，它是标准的，语言无关，这种表示方式不但人可读，而且机器可读。 可以作为Rest API的交互式文档，也可以作为Rest API的形式化的接口描述，生成客户端和服务端的代码。

网上找的Swagger生态使用图 Swagger上手难度比前两者要高出一些，当时它强大的功能足以让我们下定决心去使用它。

首先说说，swagger-editor，它是swagger提供的在线文档编辑器，编辑器传送门，长这个样子 左边是编辑器，我们可以通过编写Swagger API Spec ( yaml风格 ) 的文档，在右边的swagger-ui上直接渲染出相应API文档

其中Swagger API Spec就是Swagger提供的用来描述Rest API的语言。

Swagger API Spec对Rest API的每一个操作的请求消息的参数（Path,Query,Body,Form），响应消息的状态码和消息体的json结构都进行了详细的描述。不仅可以供给使用API的开发者学习，而且是对Rest API接口的形式化的抽象。

关于Swagger API Spec，如果想了解更多的话，可以戳这里

和rap不同的是，渲染后的页面不可以编辑。但是可以直接在页面上模拟真实的请求操作。

生态图里面另外几个东西就不多做介绍了，swagger-codegen倒是有点说法，这个工具的功能就是根据接口文档生成相应的代码。

既然可以通过文档生成代码，那当然可以通过扫描代码自动生成API文档喽～

通过在项目代码中进行一系列的配置，我们可以通过swagger直接生成项目的API文档，这下牛逼了，文档跟着代码走，代码更新，文档自动更新，不用手动维护了。

这才是swagger的正确使用姿势～

由于各个项目，框架的配置方式不同，这里就不展开来说了。目前以python框架作为开发的项目中集成的比较好的有：Django，Flask，Fastapi

比较遗憾的是，Tornado对于swagger的集成程度并不高。如果想要在Tornado中使用swagger的话，只能在接口方法的__doc__中编写Swagger API Spec，像这样： 这无疑是一个非常痛苦的过程 : (

使用到的第三方库，有兴趣的可以看看，github tornado-swagger

或许我们可以针对Tornado集成swagger进行一些定制，使之能够自动生成API文档，但从目前来讲，要完成这个目标，需要比较大的工作量。

我们已经看了几种工具，都从不同程度上帮助我们提升了文档维护的效率，那么到底该选择哪一种呢？

我的建议是： confluence + (Ray2 or Swagger)

根据不同的场景，总有一款适合你～

Swagger.io Swagger：Rest API的描述语言 Swagger Editor ray2 tornado-swagger