使用 test2doc.js 自动生成 V2EX API 文档
发布于 7 年前 作者 stackia 4230 次浏览 来自 分享

维护项目的 API 文档并不是一件轻松的事情,如果你使用过 Swagger,相信这些问题曾经困扰过你:

  • 手动编写 response body 太繁琐了
  • 为了减轻编写 response body 的工作量,又需要把服务端的 DTO 在 Swagger 文件重复写一边
  • 有时候只是一两个字段的差别,却需要在 Swagger 里新建一个 Reference Object
  • 文档总是落后于实现,更新文档要花费巨大精力

test2doc.js 就是为了解决这个问题而诞生,其核心思想是从单元测试中捕获所需信息,进而生成与代码实现完全同步的文档。

我们以 V2EX API 为例,看看 test2doc.js 如何简化文档维护工作。

先看看最终的效果是怎样的:

测试文件: https://github.com/stackia/test2doc.js/blob/master/example/v2ex/v2ex.js

生成的 Swagger 文档: https://github.com/stackia/test2doc.js/blob/master/example/v2ex/v2ex.yaml

生成的 API Blueprint 文档: https://github.com/stackia/test2doc.js/blob/master/example/v2ex/v2ex.apib

(因为 Swagger 不能够很好的支持多 Example 模式,因此事实上 API Blueprint 的文档效果会更好一些)

你可以使用 Swagger Editor / Swagger UI 来阅读 Swagger 文档,或是使用 Apiary 来展示 API Blueprint 。得益于 Swagger 和 API Blueprint 良好的社区生态,我们有大量的工具可以更好的利用这些文档。


那么,到底该如何使用 test2doc.js 呢?

首先对 API 文档基本信息做一些定义:

const doc = require('test2doc')

doc.title('V2EX 非官方 API 列表')
  .version('1.0.0')
  .desc('V2EX 非官方 API 列表,仅供参考,欢迎补充。',
    '接口来源: https://github.com/djyde/V2EX-API')
  .scheme('https', 'http')
  .host('www.v2ex.com')
  .basePath('/api')

在所有测试结束的时候,告诉 test2doc.js 输出最终文档:

after(function () {
  doc.emit(path.join(__dirname, 'v2ex.apib'), 'apib') // 生成 API Blueprint 格式文档
  doc.emit(path.join(__dirname, 'v2ex.yaml'), 'swagger') // 生成 Swagger 格式文档
})

我们以最简单的接口——“获取网站信息”为例。在不考虑 test2doc.js 的情况下,我们通常会这样来写测试用例:

const request = require('supertest')
require('should')

describe('Site', function () {
  it('should provide /api/site/info.json', async function () {
    const res = await request('https://www.v2ex.com')
      .get('/api/site/info.json')
      .expect(200)
    const body = res.body
    body.title.should.equal('V2EX')
    body.slogan.should.be.a.String()
  })
})

这里使用 supertest 辅助发起 HTTP 请求,使用 should.js 作为断言库。 node 从 7.6.0 起默认开启了 async/await ,因此我们推荐使用 async/await 。

接下来想办法让 test2doc.js 捕捉到我们请求的 URL 和响应 body。

const request = require('supertest')
require('should')

const doc = require('test2doc')

describe('Site', function () {
  doc.group('Site').basePath('/site').desc('网站相关接口').is(doc => {
    it('should provide /api/site/info.json', async function () {
      await doc.action('获取网站信息').is(async doc => {
        const res = await request(base)
          .get(doc.get('/api/site/info.json'))
          .expect(200)
        const body = doc.resBody(res.body)
        body.title.desc('站名').should.equal('V2EX')
        body.slogan.desc('口号').should.be.a.String()
      })
    })
  })
})

注意到我们用 doc.group() 对接口进行了分组,用 doc.action() 声明了想要捕获的接口,而用 .is(doc => {...}) 函数表明了 group 捕获和 action 捕获的作用范围。

我们用 doc.get('/api/site/info.json') 代替了原来直接传入的字符串,用 doc.resBody(res.body) 代替了原来的 res.bodydoc.resBody() 返回了一个经过代理的 body ,于是我们可以在想要做文档标注的字段上面使用 .desc() 来为它添加文档。

看到这里我想你应该明白了 test2doc.js 的工作原理。 test2doc.js 提供了大量方法来捕获请求、响应的各种信息,在调用 emit() 时利用了这些捕获的信息来生成文档。

完整的测试可以在 这里 找到。其中展示了 test2doc.js 的多种常用用法。


test2doc.js 依然有很大的改进空间,譬如可以对 mocha 和 supertest 进行扩展来进一步简化语法,或是跳过 Swagger 和 API Blueprint 直接生成 HTML 文档来绕过由它们造成的限制。 test2doc.js 已经应用在了我司的部分产品上,同事都说非常好用。如果你打算改善一下文档编写的工作流,不妨来试试吧。欢迎在 GitHub 反馈问题

项目地址:https://github.com/stackia/test2doc.js

回到顶部