python open api_OpenAPI初体验

问题的一开始源于客户和服务部门抱怨我的REST API文档写得不好，然后又了解到 django rest framework 利用 coreapi 能自动生成文档，再就是看到 swagger.io 上说得天花乱坠的，OpenAPI文档写完后，可以生成40种语言的客户端代码(用户都不用文档了，代码都生成了！！)，外加N种服务端stub代码，另外演示文档真心漂亮。于是我开始了研究 REST API specification的各种语言了，这里简单总结备忘下。

API specification

API sepecification有很多种语言，主流的有3种

OpenAPI (swagger)

RAML

API blueprint

我最开始研究的是openapi，没写几个endpoint我就放弃了，层次太深，缩进了几层之后，完全不知道自己在什么地方了。

我马上转去研究 api blueprint，这个挺好，有专门的emacs apib-mode，而且层次没有那么深，看起来更直白一点，甚至自己搞了 MSON 的规范，总之写起来更像是给人看的，而不是给机器看的。apib的工具相对较少，好在可以转成 openapi，然后再生成代码等等 。不过，好景不长，稍微复杂一点的API表达能力就有限了(需要复制、粘贴)，表达得也不是那么直白。

以我python程序员的角度看问题，这种东西应该由python来写，每个可利用的模块定义成function或class，然后引用一点，这样也可以将api spec拆分成小块，又要看，又好