swagger文档跨域处理_使用Swagger构建Express API Server的文档系统

如上一篇博客所说，好的文档系统对API Server至关重要，本文介绍在Express框架中使用Swagger构建一个良好的项目文档系统的基本流程，同时明确一些实践过程中肯定会遇到的问题的解决方案。本文遵循Swagger 2.0使用规范。

目标文档生成的「源」(或者说「依据」)与代码不分离，即直接用jsdoc注释生成文档；

可以用同样的「源」同时实现对接口输入输出参数的验证，最大化保证文档与后端具体实现之间的一致性；

文档在线可用性测试，并且可以完美解决跨域请求的问题；

在后端接口还未完成时，可以Mock返回数据；

最好能自动生成一些测试数据甚至自动进行测试；

从 JSDoc 到可视化文档

Step 1：定义接口模型

在Controller层每一条路由的函数注释上(具体来说，Routes目录下或Controller目录下均可，只要配置好Step 2中的swagger-jsdoc，明确「源」所在的目录即可)按Swagger YAML语法定义接口模型，示例如下:

/*** @swagger* definition:* Puppy:* properties:* name:* type: string* breed:* type: string* age:* type: integer* sex:* type: string*/

/*** @swagger* /api/puppies:* get:* tags:* - Puppies* description: Returns all puppies* produces:* - application/json* responses:* 200:* description: An array of puppies* schema: