维护项目的 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 反馈问题！