35

我需要为我创建的 REST API 编写一些 api 文档。是否有工具可以生成类似于下划线 api 文档的漂亮 html 输出？或者可能会输出一些东西作为 twitter bootstrap 样式的 html？

我看到 docco 做了注释代码，但我实际上只是想记录 API。理想情况下，我想将一个工具指向控制器文件并让它生成有关方法和路由的文档，但不显示任何源代码，除非我专门调用示例。

4

4 回答 4

45

apiDoc从源代码中的 API 注释创建文档。

集成是 API 历史，可以比较各种 API 版本级别。因此，可以追溯自上一个版本以来 API 中发生的变化。

演示：http ://apidocjs.com/example

GitHub：https ://github.com/apidoc/apidoc

于 2015-06-26T21:42:41.947 回答
13

查看 Github 上的 I/O 文档 - http://github.com/mashery/iodocs。它在 Node.js 中被黑，并且有很多社区贡献/参与。要看到它在野外工作：

Uber 简单配置模式 (JSON)，如果你不想用 JSON 手动描述它，请使用 I/O Doctor，这是一个基于 Web 的工具，用于通过 UI 导入/构建 JSON 配置：

也可在 Github 上https://github.com/brandonmwest/iodoctor

让我知道我是否可以帮助您入门。I/O Docs repo 中有很多示例配置。小心。

于 2012-08-22T00:24:09.233 回答
6

I/O Docs 或 Swagger，它们是最流行的 RESTful API 文档系统。还有RAML和Apiary。

于 2014-01-18T21:14:02.317 回答
2

test2doc.js帮助您从测试/规范生成 API 文档。因此，您始终可以获得最新更新的 API 文档，其中填充了真实的请求/响应数据。

测试代码示例：

const doc = require('test2doc')
const request = require('supertest') // We use supertest as the HTTP request library
require('should') // and use should as the assertion library

// For Koa, you should exports app.listen() or app.callback() in your app entry
const app = require('./my-express-app.js')

after(function () {
  doc.emit('api-documentation.apib')
})

doc.group('Products').is(doc => {
  describe('#Products', function () {
    doc.action('Get all products').is(doc => {
      it('should get all products', function () {
        // Write specs towards your API endpoint as you would normally do
        // Just decorate with some utility methods
        return request(app)
          .get(doc.get('/products'))
          .query(doc.query({
            minPrice: doc.val(10, 'Only products of which price >= this value should be returned')
          }))
          .expect(200)
          .then(res => {
            body = doc.resBody(res.body)
            body.desc('List of all products')
              .should.not.be.empty()
            body[0].should.have.properties('id', 'name', 'price')
            body[0].price.desc('Price of this product').should.be.a.Number
          })
      })
    })
  })
})
于 2017-03-04T21:29:41.727 回答