如何生成API文档

我需要为我创build的REST API编写一些api文档。 是否有工具，将stub出一个很好的html输出风格类似于下划线api文档？ 或者，也许会输出一些东西作为Twitter引导样式的HTML？

我看到docco没有提供代码，但实际上我只是想要loggingAPI。 理想情况下，我想指出一个工具在控制器文件，并产生有关的方法和路线文件，但不显示任何源代码，除非我特别呼吁的例子。

Answer 1

apiDoc在源代码中创build一个来自API注释的文档。

Integrated是一个API历史logging，可以比较各种API版本级别。 所以它可以回溯自上一版本以来API的变化。

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

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

Answer 2

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

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

Uber简单configuration模式（JSON）和地狱，如果你不想用JSON手工描述它，使用I / O Doctor，一个基于Web的工具，用于导入/构build带有UI的JSONconfiguration：

• http://iodoctor.net/

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

让我知道，如果我可以帮你开始。 I / O Docs仓库中有很多示例configuration。 保重。

Answer 3

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

Answer 4

test2doc.js帮助您从您的testing/规格生成API文档。 所以你可以随时获得最新的API更新文件，填入真实的请求/响应数据。

testing代码示例：

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