zysam
commented
8 years ago swagger-node 实践
介始
一个工具（轮子），基于 node.js 来打造 swagger 风格的 http 服务。可以说是，跟 sails， hapi 类似，脚手架还可以是基于它们的打造。
核心是文档。 文档也是API，API分四部分，详见 api 目录，目录功能说明在仓库的 doc 目录下。 文档提供友好的网页工具编辑、预览。
使用说明
- http 应用框架。
swagger project create <name>。生成一个项目脚手架。可以选择 node 的主流框架如：express, restify, hapi, sails等（没有 koa）；然后就是 swagger-node 框架的约定或API。 swagger project edit。project root 下，找到 ./api/swagger/swagger.yml，可以在线编辑 swagger 文档，实时预览网页，实时保存于当前项目；也可以本地编辑 swagger.yml ，刷新网页预览。
核心
creat project -> framework as mw -> runner adapt framework -> tools； 分层设计不够清晰，大致是以上流程，难扩展。所以 koa 没有加进来。 koa 使用 generator 函数与其它框架的普通函数格格不入。
扩展
- 看到整个设计后，觉得接入 koa 很麻烦，根本上要重构。
- 可以通过 genCode 自定义模版，生成自己的API。
总结
优点：
- 耳目一新。基于文档来构建应用。
- 工具还算足够，生态不弱。现有工具基于文档定制自己的API。
- 修改文档，预览文档相当友好。
缺点：
- 基于文档沟通不够顺畅、彻底。没有从根本性解决更新文档后通知变更，修改API的痛点，还是回到传统沟通。如果回到传统，文档很快会弃之不用。
- 难扩展，易死亡。上面说的由于分层不好，难接入。而且难以及时更新官方API。另外：作者好像不想维护它了。
- 基于文档的框架，感觉上不可靠。细节太多，无法掌握。
- 定位不够清晰。于生产环境，还是开发环境？生产环境不够安全，开发环境过于复杂。
程序员最烦一件事，1 写文档；2 别人没写文档；
swagger 似乎能解决这个麻烦，如标题所说；
另外还有，基于文档来生成服务的，无缝与 express, hapi, koa 等框架接入，还支持 mongodb, validator等等。不过，我是不会考虑用的。
所以，你只要写 swagger 的文档就好。
当然，搭建相关服务啦。
不只，配置相关服务发现更新文档，自定义模版等等。。。
好像又引入一个轮子，但好像值得一试。
实践再续。