使用 test2doc.js 自动生成 V2EX API 文档

[jsq2627]

维护项目的 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.body。doc.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

[sunkuku]

👍