node-autodoc
A test-driven generator for API documentation. Inspired by autodoc and supertest.
Why need this
Some people are not happy to maintain the API documentation when dealing with the large project. Then, it causes so many confusions and problems when someone new to use previous APIs.
This library is to generate a documentation by given the test cases. It renders the API documentation according to the input and output of each http request.
Work flow
Example
There is also an example inside the repo. Check this out!
Render mode
Default template
It renders the documentation using ejs template engine by default.
Custom template
If you have better templates, you can specify the templateDir
to let AutoDoc render your templates.
You may want to check out the default templates first, then design your templates.
Custom render function
If you have better idea to render the API doc page, you can also pass a callback in renderPage
to make your custom renders.
agent.renderPage((currentAgent) => {
// Assemable your render data
const myRenderData = {
title: currentAgent.title,
description: currentAgent.description,
docMetaCollection: currentAgent.docMetaCollection,
tableOfContent: currentAgent.docMetaCollection.map((docMeta) => ({
link: `#${encodeURIComponent(docMeta.title)}`,
title: docMeta.title,
})),
};
// Your render function
customRender(myRenderData);
})
A very common case would be like: Send all the docMetaCollection
to your documentation server and generate your own documentation website.
API
Most of the usages are same as supertest. Its APIs are really neat and simple.
The extra APIs this library enhances are below.
AutoDocAgent
const agent = new AutoDocAgent(
app,
{
outputFilename: 'users.html',
title: 'Users API Documentation',
description: 'A small and simple documentation for how to deal with /users api',
outputDir,
templateDir,
}
)
AutoDocAgent
parameter | value |
---|---|
app | Your express app, or koa app |
options | Extends from supertest options |
options
parameter | description |
---|---|
outputFilename | The file name of current api document |
outputDir | Current api document output directory |
templateDir | Ejs template directory. It will use the default template if ignore it |
title | Title of current api doc |
description | Description of current api doc |
AutoDocAgent.clear
Clear the given outputDir
directory.
AutoDocAgent.clear(outputDir)
AutoDocAgent.renderIndex
Render the home page by given all agents.
AutoDocAgent.renderIndex({
title: 'My API Documentation',
description: 'This is my first documentation for testing, haha~',
author: 'Haixiang',
agents,
outputDir,
templateDir,
});
parameter | value |
---|---|
title | Home page title |
description | Home page description |
author | Author |
agents | AutoDocAgent instance array |
outputDir | Output directory |
templateDir | Ejs template directory. It will use the default template if ignore it |
restful method
When calling the restful method, it's calling the restful method of supertest. The only difference is that you can pass the second parameter to render title and description.
agent.get('/users', {
title: 'Fetch all users',
description: 'To get all user infomation'
})
renderPage
Render current API doc.
agent.renderPage()
If you have better idea to render the API doc page, you can also put a callback in there to make your custom renders.
agent.renderPage((currentAgent) => {
// Assemable your render data
const myRenderData = {
title: currentAgent.title,
description: currentAgent.description,
docMetaCollection: currentAgent.docMetaCollection,
tableOfContent: currentAgent.docMetaCollection.map((docMeta) => ({
link: `#${encodeURIComponent(docMeta.title)}`,
title: docMeta.title,
})),
};
// Your render function
customRender(myRenderData);
})