Question

我需要为我创建的REST API编写一些api文档。是否有工具可以在下划线api文档中找出类似风格的html输出？或者也许某些东西会输出一些作为Twitter引导程序的样式的html？

我看到docco确实编写了代码，但我实际上只是想要记录API。理想情况下，我想在控制器文件中指出一个工具，让它生成有关方法和路由的文档，但不显示任何源代码，除非我特别提出示例。

Answer 1

apiDoc在源代码中根据API注释创建文档。

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

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

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

Answer 2

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

Uber简单配置架构（JSON），如果您不想在JSON中手动描述它，那么使用I / O Doctor，一个基于Web的工具，用于使用UI导入/构建JSON配置：

http://iodoctor.net/

也可以在https://github.com/brandonmwest/iodoctor

的Github上找到

如果我可以帮助您入门，请告诉我。 I / O Docs仓库中有很多示例配置。小心。

Answer 3

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

Answer 4

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
          })
      })
    })
  })
})

如何生成api文档

4 个答案: