使用 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 界面似乎会友好一点,但是也不能排除文档更新不及时的情况,还有一些问题需要克服吧。

如果您觉得文章不错,可以通过赞助支持我

标签: 知识, 代码段, node.js

添加新评论