node.js 如何生成api文档
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/11969542/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
how to generate api documentation
提问by MonkeyBonkey
I need to write some api documentation for a REST API that I've created. Are there tools that will stub out a nice html output similar in style to the underscore api documentation? Or perhaps something that will output something as a twitter bootstrap styled html?
我需要为我创建的 REST API 编写一些 api 文档。是否有工具可以生成与下划线 api 文档风格相似的漂亮 html 输出？或者可能会输出一些东西作为 twitter bootstrap 样式的 html？
I see that docco does annoated code, but I'm actually just looking to document the API only. Ideally I'd like to point a tool at the controller file and have it generate documentation about the methods and routes but not show any source code unless I specifically call out examples.
我看到 docco 做了带注释的代码，但我实际上只是想记录 API。理想情况下，我想将一个工具指向控制器文件并让它生成有关方法和路由的文档，但除非我特别指出示例，否则不显示任何源代码。
回答by Diogo Cardoso
apiDoccreates a documentation from API annotations in your source code.
apiDoc根据源代码中的 API 注释创建文档。
Integrated is an API history, with that various API version levels can be compared. So it can be retraced what changed in the API since the last version.
集成是 API 历史，可以比较各种 API 版本级别。因此可以追溯自上一版本以来 API 中发生的变化。
Demo: http://apidocjs.com/example
演示：http: //apidocjs.com/example
Github: https://github.com/apidoc/apidoc
Github：https: //github.com/apidoc/apidoc
回答by mansilladev
Check out I/O Docs on Github - http://github.com/mashery/iodocs. It's hacked in Node.js, and has a lot of community contribution/involvement. To see it working in the wild:
查看 Github 上的 I/O 文档 - http://github.com/mashery/iodocs。它在 Node.js 中被黑了，并且有很多社区贡献/参与。要查看它在野外工作：
Uber simple configuration schema (JSON), and hell, if you don't want to describe it all by hand in JSON, use I/O Doctor, a web-based tool for importing/building JSON configs with a UI:
Uber 简单配置模式 (JSON) 以及地狱，如果您不想在 JSON 中手动描述它，请使用 I/O Doctor，这是一个基于 Web 的工具，用于导入/构建带有 UI 的 JSON 配置：
Also available on Github at https://github.com/brandonmwest/iodoctor
也可在 Github 上获取，网址为https://github.com/brandonmwest/iodoctor
Let me know if I can help you get started. There are plenty of example configs in the I/O Docs repo. Take care.
如果我可以帮助您开始，请告诉我。I/O Docs 存储库中有很多示例配置。小心。
回答by theofpa
回答by Stackia
test2doc.jshelps you generate API documentation from your tests/specs. So you can always get the latest update-to-date API documents, populated with real request/response data.
test2doc.js可帮助您从测试/规范中生成 API 文档。因此，您始终可以获得最新的更新到最新的 API 文档，其中填充了真实的请求/响应数据。
Test code example:
测试代码示例：
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
})
})
})
})
})
