如何生成API文档

Question

我需要为我创建的REST API撰写一些API文档。是否有工具可以生成类似于underscore API文档风格的漂亮HTML输出？或者可能会输出类似Twitter Bootstrap样式的HTML文件？

我看到Docco可以做注释，但实际上我只想记录API。理想情况下，我想把一个工具指向控制器文件，并让它生成关于方法和路由的文档，除非我特别调用示例，否则不显示任何源代码。

- MonkeyBonkey

---

我会查看Express.js如何生成它的文档。它使用了一些node脚本、shell脚本和dox的组合。 - Dominic Barnes

Answer 1

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

它还包括API历史记录，可以比较不同的API版本级别。 因此可以追溯自上一个版本以来API发生的变化。

Demo: http://apidocjs.com/example

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

- Diogo Cardoso

---

请注意，这个库已不再被积极维护。 - d4nyll

有没有一种方法可以反过来创建呢？即从文档中创建API注释。 - GBRocks

最近有几个新版本发布了，所以这个项目仍然有希望。 - MrSegFaulty

我现在看到这个仓库正在积极维护。 - Gagan

Answer 2

在Github上查看I/O Docs - http://github.com/mashery/iodocs 。它使用Node.js编写，并得到了许多社区的贡献和参与。要在实际环境中查看其工作情况：

• http://iodocs.docusign.com
• http://console.datasift.com/datasift

配置模式非常简单（JSON），如果你不想手动描述所有内容，请使用I/O Doctor，这是一个基于Web的工具，可用于导入/构建带有UI的JSON配置：

• http://iodoctor.net/

还可以在Github上找到它：https://github.com/brandonmwest/iodoctor

如果需要帮助启动，请告诉我。 I / O Docs存储库中有很多示例配置。保重。

- mansilladev

---

您是否知道有什么方法可以从.NET WebAPI ApiExplorer中生成Mashery I/O文档（类似于Swagger的方式）？ - Michael Ibarra

请修正答案中的链接。其中一些已经失效了。 - Slava Fomin II

请注意，该库已不再得到积极维护。 - d4nyll

Answer 3

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

- Theofilos Papapanagiotou

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

- Stackia