SpecTree: Yet another tool to generate OpenAPI document and validate request & response with Python annotations.

之前分别跟 Flask 和 Flacon 写了插件来做这件事，本来想着可能不太会去做一个 general core 了，够用就行了。然而马上就被打脸了。

目前遇到的问题主要有：

• 两者有不少共同的逻辑，每次需要调整的时候两边都需要改，还不敢保证效果一致
• 写 test 的话，又要写很多重复的 test case 了，文档同理
• 如果想支持其他 framework，例如 starlette 就需要从头写了，虽然可以参考
• 两个包也存在一部分不一致的地方，感觉设计的时候很多地方欠考虑
• 我想造轮子了

说干就干……然后 spectree 就这样诞生了。主要完成了以下改进：

• 作为一个 core，可以增加对其他 framework 的支持，只需要实现几个方法即可
• 增加了 test，不然每次都搞不清楚改动是不是影响到其他模块了，不写测试心里没底
• 参考了一些 API design guideline，重新设计了 response 的格式，显式声明 status code 和对应的 data model
• 统一的 request data 获取方式，都从 request.context 中获取
• 使用各个 framework 原生的返回样式，减少代码的修改量
• 关于 design 方面的考虑，都写进 issue 里面打上 ‘design’ 的 label，方面之后查询
• 顺手增加了 headers 和 cookies 的支持
• 尽可能拆分开 core 部分处理的内容和针对每个 framework 需要做的不同处理，可以适配 sync 和 async
• 添加了 lgtm.com 检查代码中的问题，当然这个 code quality 真的就是看着开心，A/A+ 大概是常态……

简单写点感想吧：

• 动手之前很有必要广泛阅读相关的各种 standard，guidelines，或 best practice
• 中间遇到设计上的考量，写到 issue 里备查，方便自己和他人查阅
• release 最终版之前，最好留点余地，说不定会发现什么 bug 或者 interface 设计问题
• 必要的测试真的很有必要，这样每次添加 feature 或者修改 bug 都能心里有点底，写测试的过程也有助于发现一些小问题
• 多跟社区的人交流一下，广泛听取群众的意见……
• 还是不太会推广，就简单去 framework 的 add-ons 页面加了一条
• Python descriptor 确实很复杂……