使用 Swagger Mock API

Swagger 是一个完整的从设计到文档到 Mock 的 API 生态体系。

它会帮助你进行一定的设计，对于不符合的设计会报错，你需要掌握它的 yaml 文件书写规范，可以通过 OpenAPI Specification 稍作了解。

最初写文档可能会因为 yaml 语法不熟报一堆 error，习惯之后基本上也没啥问题，这样可以摒弃一些不规范的文档带来的沟通成本。

当然，今天就不介绍这一部分的信息了，在http://editor.swagger.io/#/会存在默认的示例。

在 Editor 中可以根据文档点击 Generate Server并且选择 server 的类型就能快速生成 Mock 的 Server 的压缩包，可以直接运行。

对于前端而言，这样的方式当然是最简单粗暴的啦，只要后端提供文档就行

实际上是使用了swagger-tools

只要使用：

1'use strict';
2
3var app = require('connect')();
4var http = require('http');
5var swaggerTools = require('swagger-tools');
6
7var serverPort = 3000;
8
9// swaggerRouter configuration
10var options = {
11  controllers: './controllers',
12  useStubs: process.env.NODE_ENV === 'development' ? true : false // Conditionally turn on stubs (mock mode)
13};
14
15// The Swagger document (require it, build it programmatically, fetch it from a URL, ...)
16var swaggerDoc = require('./api/swagger.json');
17
18// Initialize the Swagger middleware
19swaggerTools.initializeMiddleware(swaggerDoc, function (middleware) {
20  // Interpret Swagger resources and attach metadata to request - must be first in swagger-tools middleware chain
21  app.use(middleware.swaggerMetadata());
22
23  // Validate Swagger requests
24  app.use(middleware.swaggerValidator());
25
26  // Route validated requests to appropriate controller
27  app.use(middleware.swaggerRouter(options));
28
29  // Serve the Swagger documents and Swagger UI
30  app.use(middleware.swaggerUi());
31
32  // Start the server
33  http.createServer(app).listen(serverPort, function () {
34    console.log('Your server is listening on port %d (http://localhost:%d)', serverPort, serverPort);
35  });
36});
37

在 docs 中提供了文档，靠着访问 API 路径即可直接使用 API，非常方便。

当然，这样的方式仍然存在几个问题，在我维护项目文档的时候也遇到了：

文档更新不及时，尤其是在开发后期，接口做过调整之后容易忽略文档的更新，文档就不能起到原来的效果了。
文档内容过长，难以继续维护
错误提示不够友好，初期上手 Debug 困难。

如果存在 GUI 界面似乎会友好一点，但是也不能排除文档更新不及时的情况，还有一些问题需要克服吧。

评论 (0)