📝 Generate a Simple and Portable Markdown documentation for your API
apidoc-markdown uses apiDoc internally. To generate your nice Markdown documentation, you first need to add some apiDoc API documentation comments in your code.
Take a look at https://apidocjs.com/ to discover it if it's your first time using it! 😉
You create your API documentation directly in your code with comments like this:
/**
* @api {post} /admin/invite/new Send Invite
* @apiPermission GlobalAdmin
* @apiDescription Create & email a new Strider invite.
* @apiName SendInvite
* @apiGroup Admin
* @apiVersion 1.0.0
*
* @apiExample {curl} CURL Example:
* curl -X POST -d invite_code=xoxox -d email=me[at]email.com http://localhost/invite/new
*
* @apiParam (RequestBody) {String} invite_code The invite code/token to use in the invitation
* @apiParam (RequestBody) {String} email The email address of the new user being invited
*/
app.post('/invite/new', (req, res) => res.end())Some examples are available in the example directory.
Take a look at example/strider/api.md which shows a real-world example taken from the Strider API.
# For the global CLI
pnpm install --global apidoc-markdown
# For programmatic usage or local project CLI install
pnpm install apidoc-markdownThen, generate your documentation using your newly added command apidoc-markdown or programmatically.
Note: Node.js v14+ minimum is required. apidoc-markdown uses apidoc-light internally.
Generate a Simple and Portable Markdown documentation for your API.
Usage: apidoc-markdown -i <path> -o <output_file> [-t <template_name>] [--multi] [--createPath] [--prepend <file_path>]
Options:
--version Show version number [boolean]
-i, --input Input source files path [string] [required] [default: "src"]
-o, --output Output file or directory to write output to. [string] [required]
-t, --template Name of the template to be used (`default`, `bitbucket`) or path to an EJS template file. [string] [default: "default"]
--header Path to file content to add at the top of the documentation. [string]
--footer Path to file content to add at the bottom of the documentation. [string]
--prepend Path to file content to add before route groups documentation. [string]
--multi Output one file per group to the `output` directory. [boolean] [default: false]
--createPath Recursively create directory arborescence to the `output` directory. [boolean] [default: false]
-h, --help Show help [boolean]
Examples:
apidoc-markdown -i src -o doc.md Generate from `src` source files to `doc.md`
apidoc-markdown --input src --output doc.md Generate from `src` source files to `doc.md`
apidoc-markdown -i src -o doc.md -t bitbucket Generate from `src` source files to `doc.md` using the `bitbucket` template
apidoc-markdown -i src -o doc.md -t my_custom_template.md Generate from `src` source files to `doc.md` using a provided template file
apidoc-markdown -i src -o doc --multi Generate from `src` source files to `doc/<group>.md`
apidoc-markdown - https://github.com/rigwild/apidoc-markdown
Generate documentation (See ./example/basic/example.md).
apidoc-markdown -i src -o doc.md
You can select a provided template by using -t or --template (default, bitbucket).
apidoc-markdown -i src -o doc.md -t bitbucket
You can pass the path to your own template by using -t or --template.
apidoc-markdown -i src -o doc.md -t my_custom_template.md
You can inject a header, footer or prepend section in your documentation with the content of a file using --header, --footer and --prepend.
apidoc-markdown -i src -o doc.md --header header.md
apidoc-markdown -i src -o doc.md --footer footer.md
apidoc-markdown -i src -o doc.md --prepend prepend.md
apidoc-markdown -i src -o doc.md --header header.md --footer footer.md --prepend prepend.md
Generate documentation with one file per group (See ./example/multi).
apidoc-markdown -i src -o doc --multi
Install apidoc-markdown as a dev dependency.
pnpm install -D apidoc-markdownAdd the following script to your package.json file (src is where are stored your source files containing some apiDoc annotations).
{
"scripts": {
"doc": "apidoc-markdown -i src -o DOCUMENTATION.md"
}
}Run the npm script to generate the DOCUMENTATION.md file.
pnpm docGenerate mardown documentation using the file system and creating output file(s).
import path from 'path'
import { generateMarkdownFileSystem } from 'apidoc-markdown'
const documentation: Doc = await generateMarkdownFileSystem({
/** Input source files path */
input: path.resolve(__dirname, 'path', 'to', 'your', 'sources', 'directory'),
/** Output file or directory to write output to */
output: path.resolve(__dirname, 'doc.md'),
/** Optional: Name of template to be used (`default`, `bitbucket`)
* or path to EJS template file
* or raw EJS plain text template
* (will use default template if ommitted). */
template: 'default',
/** Optional: Path to file content to add at the top of the documentation */
header: path.resolve(__dirname, 'add-this-to-the-top'),
/** Optional: Path to file content to add at the bottom of the documentation */
footer: path.resolve(__dirname, 'add-this-to-the-bottom'),
/** Optional: Path to file content to add before route groups documentation */
prepend: path.resolve(__dirname, 'prepend-this-to-api-routes'),
/** Optional: Output one file per group to the `output` directory */
multi: false,
/** Optional: Recursively create directory arborescence to the `output` directory */
createPath: true
})
// Output
type Doc = Array<{
name: string // Api group name
content: string // Documentation content
}>
// (if `multi` is `false`, you get an array with 1 element!)Generate mardown documentation by passing directly the apiDoc output.
import { generateMarkdown } from 'apidoc-markdown'
const documentation: Doc = await generateMarkdown({
/** apiDoc project JSON data object `apidoc.json` file content) */
apiDocProjectData: { name: 'test', version: '0.13.0' /* ... */ },
/** apiDoc documentation JSON data object (`api_data.json` file content) */
apiDocApiData: [{ type: 'get', url: '/define' /* ... */ }],
/** Optional: Name of template to be used (`default`, `bitbucket`)
* or path to EJS template file
* or raw EJS plain text template
* (will use default template if ommitted). */
template: 'my EJS template <%= project.name %> v<%= project.version %>',
/** Optional: Content to add at the top of the documentation */
header: 'Add this text at the top of the doc!',
/** Optional: Content to add at the bottom of the documentation */
footer: 'Add this text at the bottom of the doc!',
/** Optional: Content to add before route groups documentation */
prepend: 'Prepend this before the API routes documentation!',
/** Optional: Generate one documentation output per group */
multi: false
})
// Output
type Doc = Array<{
name: string // Api group name
content: string // Documentation content
}>
// (if `multi` is `false`, you get an array with 1 element!)The header, footer and prepend options can be configured directly in your apidoc.json (see apidoc.json documentation).
Add it like this:
{
"name": "test",
"version": "0.1.2",
"description": "test",
"title": "test",
"url": "https://test.example.com/",
"header": {
"filename": "header.md"
},
"footer": {
"filename": "footer.md"
},
"prepend": {
"filename": "prepend.md"
}
}Note: This only works if you use the CLI or generateMarkdownFileSystem.
You can choose the order in which the documentation groups gets generated by adding an order key in apidoc.json. See example apidoc.json and generated example output.
Note: This is only useful when generating the documentation to a single output file (multi is false).
Share your custom templates in this discussion!
Suggest any feature you would like by creating an issue or a pull request.
When reporting bugs, please fill the issue template correctly with as much info as possible to help me debug and understand what's happening.
⭐ Star the project to help it grow! 😄