启动工程命令行切换到工程根目录下，运行以下命令，运行结果如清单 5。
# swagger project start
工程正确启动后会提示我们尝试打开链接： 。这个链接是工程默认带的一个例子，我们可以在 api/swagger/swagger.yaml 文件中找到这个 API 请求的定义，以及响应这个请求的 controller。
清单 5. 启动工程1
2
3
4
5
6
7
| D:\innovation\SwaggerProject>swagger project start
Starting: D:\innovation\SwaggerProject\app.js...
project started here: http://localhost:10010/
project will restart on changes.
to restart at any time, enter `rs`
try this:
curl http://127.0.0.1:10010/hello?name=Scott
|
编辑 API 文档工程支持在浏览器中显示、编辑、保存、测试 api/swagger/swagger.yaml 文档。具体步骤如下：
1. 首先启动在线编辑器。打开一个新的命令行窗口，运行命令: # swagger project Edit，运行结果如清单 6。工程默认创建的 swagger.yaml 文件会在浏览器中显示，结果如图 3。
清单 6. 编辑 API 文档命令1
2
3
4
| D:\innovation\SwaggerProject>swagger project edit
Starting Swagger Editor.
Opening browser to: http://127.0.0.1:49965/#/edit
Do not terminate this process or close this window until finished editing.
|
图 3. 在线编辑 API 文档 2. 在浏览器里编辑 YAML 文件。工程支持在浏览器中直接修改 API 文档，修改的值会直接保存到 api/swagger/swagger.yaml 文件中。我们可以将自己项目的 Swagger API 文档保存成 YAML 格式更新到 Mock Server 中。YAML 文件编辑过后，工程会自动加载最新的 API 文档。
3. 添加关键词到 API 文档。当 API 请求被 Mock Server 拦截后，Server 通过读取 swagger.yaml 文件中指定的关键词的值来决定接下来要做何响应。除了定义 API 需要的关键词外，我们还需要在每个 Path 定义中加入以下两个关键词，来指定每个 API 的 controller 和 function。具体代码请参考清单 7。
- x-swagger-router-controller：这个值需要设置成响应 API 请求的 controller 文件的名字。比如 controller 文件为 hello_world.js， 那么关键词的值就是 hello_world。
- operationId：这个值需要设置成响应 API 请求的 controller 文件中相应的方法。
清单 7. 编辑 YAML 文档1
2
3
4
5
6
7
| /hello:
# binds a127 app logic to a route
x-swagger-router-controller: hello_world
get:
description: Returns 'Hello' to the caller
# used as the method name of the controller
operationId: hello
|
4. 测试 API 文档。API 文档编辑完成后，我们可以直接在浏览器的右侧添加参数向 Mock Server 发送 API 请求，测试 API 文档的正确性。
编写 controller当 API 请求被 Mock Server 拦截后，由 controller 决定要如何响应这个 API 请求。所以需要对应所有的 API 请求，编写响应逻辑支持前端开发。需要注意的是要把响应的入口方法导出。这里有个小技巧，我们可以在 controller 的入口将请求的 URL 输出到 console 或者日志中，这样便于在开发的过程中追踪 API 请求。具体代码请参考清单 8：
清单 8. 编写 controller1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| module.exports = { viewContent };
function viewContent(req, res) {
console.log('viewContent : url=' + req.url);
var type = req.swagger.params.type.value
var htmlPath = '';
if (type === 'text'){
htmlPath = path.join(webStaticPath, 'html','text.html');
}
res.sendFile(htmlPath, function (err) {
if (err) {
console.error(err);
} else {
console.log('Sent:', htmlPath);
}
});
}
|
添加 proxy 功能当后端代码部分 API 开发完成后，我们希望能及时对已完成代码部分进行前后端联调。这时可以给 Mock Server 添加 proxy 的功能，使 Mock Server 接到的请求都转到真正的后端服务环境上去。 这样前端就可以在开发环境中直接访问真正的后端服务，而不必担心跨域的问题。这里我们使用 http-proxy-middleware 包来实现 proxy 功能。
首先在 package.json 文件中添加 http-proxy-middleware lib 包，然后工程里运行以下命令安装 node module：
# npm install
然后修改我们的 Mock Server 的入口文件 app.js，具体代码请参考清单 9：
清单 9. 添加 proxy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| var proxy = require('http-proxy-middleware');
/**
* Configure proxy middleware
*/
var targetUri = http + '://' + remoteHostName:port ;
var routePathList = ["/docs/docsrv","/docs/api"];
var docsProxy = proxy({
target: targetUri,
changeOrigin: true,
logLevel: 'debug',
secure: false
})
for(var i = 0; i routePathList.length; i++){
app.use(routePathList, docsProxy);
}
|
|
