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-markdown
Then, 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-markdown
Add 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 doc
Generate 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! π