使用 Swagger Mock API

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

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

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

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

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

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

实际上是使用了swagger-tools

只要使用：

'use strict';

var app = require('connect')();
var http = require('http');
var swaggerTools = require('swagger-tools');

var serverPort = 3000;

// swaggerRouter configuration
var options = {
  controllers: './controllers',
  useStubs: process.env.NODE_ENV === 'development' ? true : false // Conditionally turn on stubs (mock mode)
};

// The Swagger document (require it, build it programmatically, fetch it from a URL, ...)
var swaggerDoc = require('./api/swagger.json');

// Initialize the Swagger middleware
swaggerTools.initializeMiddleware(swaggerDoc, function (middleware) {
  // Interpret Swagger resources and attach metadata to request - must be first in swagger-tools middleware chain
  app.use(middleware.swaggerMetadata());

  // Validate Swagger requests
  app.use(middleware.swaggerValidator());

  // Route validated requests to appropriate controller
  app.use(middleware.swaggerRouter(options));

  // Serve the Swagger documents and Swagger UI
  app.use(middleware.swaggerUi());

  // Start the server
  http.createServer(app).listen(serverPort, function () {
    console.log('Your server is listening on port %d (http://localhost:%d)', serverPort, serverPort);
  });
});

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

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

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

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