how to generate api documentation
Solution 1
apiDoc creates a documentation from API annotations in your source code.
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.
Demo: http://apidocjs.com/example
Github: https://github.com/apidoc/apidoc
Solution 2
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:
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:
Also available on Github at 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.
Solution 3
I/O Docs or Swagger, which are the most popular RESTful API documentation systems. There is also RAML and Apiary.
Solution 4
test2doc.js helps 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.
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
})
})
})
})
})
MonkeyBonkey
CTO of Pictorious.com, a mobile app for turning photo sharing into a fun meme-game.
Updated on March 05, 2020Comments
-
MonkeyBonkey over 4 years
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?
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.
-
Michael Ibarra over 10 yearsIs there a way, that you know of, to generate Mashery I/O Docs from the .NET WebAPI ApiExplorer (similar to the way Swagger does)?
-
Slava Fomin II over 7 yearsPlease correct the links in the answer. Some of them are broken.
-
d4nyll over 6 yearsNote that this library is no longer actively maintained.
-
d4nyll over 6 yearsNote that this library is no longer actively maintained.
-
GBRocks over 5 yearsIs there a way to create the reverse? i.e. create API annotations from documentation.
-
MrSegFaulty over 4 yearsA few new releases have be done lately. So there's still hope for the project.