Swagger-node-express用法

Question

我想分享一下我对https://github.com/swagger-api/swagger-node-express的看法

它在Github上有564颗星,所以我认为使用它是合理的,但是:

• 为什么我应该使用像addGet/addPost这样的方法,并通过HTTP方法拆分我的控制器
• 我为什么要让模型涉及路由？
• 我可以使用验证器进行身份验证,但我必须选择一些应该受到保护的路径.它复制逻辑,存储在swagger json文件中.

是不是有一个静态swagger.json并在其上构建Express路由的正确方法？或者我可能不了解一些实践

Answer 1

Swagger只是一个规范.你可以手工制作一个没有任何代码的swagger规范,将规范提供给一个符合swigger-ui标准的页面,并且它"可以工作".您可以使用完全定义的API并使用UI页面"运行"它.对于没有招摇的快递也是如此 - 你可以做很多整洁的事情!但是需要付出一些努力才能以宽广的方式记录API.

如果要使用swagger-node-express,则需要将代码与API文档相结合.这可以为您节省大量时间,并在同一个文件中保留更改等.但是,就像您提出的所有问题一样,您必须以swagger-node-express方式执行操作.比单独做两者更快,但必须遵循一些限制.

还有其他一些swagger包从不同角度解决这个问题.我见过一些尝试从Express/Restify路线自动构建swagger文档.swagger-node-express的另一种选择是swagger-tools,它甚至包括验证,但我猜你在某种程度上有限制写Express而没有任何swagger集成.

您可以手动(或使用某些YAML,jsDoc包或生成器)自由构建swagger文档,但在写入路由后需要一些额外的时间.另外,它是一个单独的地方来维护你的文档,如果不是放弃的话,它们总会在某些时候不同步.使用swagger-node-express主要是节省时间,即使有其缺点,也可能值得替代方案的额外开发工作.