lincanbin / apidoc-markdown
Generate API documentation in markdown format from API annotations in your source code.
This package is auto-updated.
Last update: 2024-11-28 23:03:20 UTC
README
Generate API documentation in markdown format from API annotations in your source code.
Preface
All examples in this document use the Javadoc-Style (can be used in C#, Go, Dart, Java, JavaScript, PHP, TypeScript and all other Javadoc capable languages):
/**
* This is a comment.
*/
Install
composer global require lincanbin/apidoc-markdown:~1.0
Run
apidoc-markdown -i myapp/ -o apidoc/
or
apidoc -i myapp/ -o apidoc/
Creates an apiDoc of all files within dir myapp/, and put all output to dir apidoc/.
Without any parameter, apiDoc generate a documentation from all .cs .dart .erl .go .java .js .php .py .rb .ts files in current dir (incl. subdirs) and writes the output to ./apidoc/.
Command Line Interface
Show command line parameters:
apidoc-markdown -h
Important parameters:
Configuration (apidoc.json)
The optional apidoc.json in your projects root dir includes common information about your project like title, short description, version and configuration options like header / footersettings or template specific options.
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
If you use a package.json (e.g. in a node.js project), all apidoc.json settings can be done in package.json too, just add them under the "apidoc": { } parameter.
package.json
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"apidoc": {
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
}
Settings for apidoc.json
Template specific settings
The following settings are specific for the default template of apiDoc.
Header / Footer
In your projects apidoc.json you can add a header and footer.
The title will be visible in the navigation. The filename should be a markdown textfile.
{
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
}
}
Basic
In this basic example we have a small project file and an apidoc.json.
{
"name": "example",
"version": "0.1.0",
"description": "A basic apiDoc example"
}
From apidoc.json apiDoc get the name, version and description of your project.
The file is optional (it depend on your template if the data is required).
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
A documentation block starts with /** and end with */.
This example describes a GET Method to request the User Information by the user's id.
@api {get} /user/:id Request User information is mandatory, without @apiapiDoc ignores a documentation block.
@apiName must be a unique name and should always be used.
Format: method + path (e.g. Get + User)
@apiGroup should always be used, and is used to group related APIs together.
All other fields are optional, look at their description under apiDoc-Params.
Inherit
Using inherit, you can define reusable snippets of your documentation.
{
"name": "example-inherit",
"version": "0.1.0",
"description": "apiDoc inherit example"
}
/**
* @apiDefine UserNotFoundError
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiUse UserNotFoundError
*/
/**
* @api {put} /user/ Modify User information
* @apiName PutUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
* @apiParam {String} [firstname] Firstname of the User.
* @apiParam {String} [lastname] Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
*
* @apiUse UserNotFoundError
*/
In this example, a block named UserNotFoundError is defined with @apiDefine.
That block could be used many times with @apiUse UserNotFoundError.
In the generated output, both methods GET and PUT will have the complete UserNotFoundError documentation.
To define an inherit block, use apiDefine.
to reference a block, use apiUse. apiGroup and apiPermission are use commands to, but in their context the not inherit parameters, only title and description (in combination with apiVersion).
Inheritation only works with 1 parent, more levels would make the inline code unreadable and changes really complex.
Versioning
A useful feature provided by apiDoc is the ability to maintain the documentation for all previous versions and the latest version of the API. This makes it possible to compare a methods version with its predecessor. Frontend Developer can thus simply see what have changed and update their code accordingly.
In the example, click top right on select box (the main version) and select Compare all with predecessor.
- The main navigation mark all changed methods with a green bar.
- Each method show the actual difference compare to its predecessor.
- Green marks contents that were added (in this case title text changed and field
registeredwas added). - Red marks contents that were removed.
You can change the main version (top right) to a previous version and compare older methods with their predecessor.
{
"name": "example-versioning",
"version": "0.2.0",
"description": "apiDoc versioning example"
}
In order to avoid code bloat when API documentation changes over time, it is recommended to use a separate history file named _apidoc.js. Before you change your documentation block, copy the old documentation to to this file, apiDoc will include the historical information automatically.
/**
* @api {get} /user/:id Get User information
* @apiVersion 0.1.0
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
example.js (your current project file)
/**
* @api {get} /user/:id Get User information and Date of Registration.
* @apiVersion 0.2.0
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
* @apiSuccess {Date} registered Date of Registration.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
Important is to set the version with @apiVersion on every documentation block.
The version can be used on every block, also on inherit blocks. You don't have to change the version on an inherit block, the parser check automatically for the nearest predecessor.
Full example
This is a complex example with inherit, versioning file and history file _apidoc.js, explanation is within code and generated documentation.
Files:
apiDoc-Params
Structure parameter like:
@apiDefine
is used to define a reusable documentation block. This block can be included in normal api documentation blocks. Using @apiDefine allows you to better organize complex documentation and avoid duplicating recurrent blocks.
A defined block can have all params (like @apiParam), except other defined blocks.
@api
@api {method} path [title]
Required!
Without that indicator, apiDoc parser ignore the documentation block.
The only exception are documentation blocks defined by @apiDefine, they not required @api.
Usage: @api {get} /user/:id Users unique ID.
Example:
/**
* @api {get} /user/:id
*/
@apiDefine
@apiDefine name [title]
[description]
Defines a documentation block to be embedded within @api blocks or in an api function like @apiPermission.
@apiDefine can only be used once per block
By using @apiUse a defined block will be imported, or with the name the title and description will be used.
Usage: @apiDefine MyError
Example:
/**
* @apiDefine MyError
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/
/**
* @api {get} /user/:id
* @apiUse MyError
*/
/**
* @apiDefine admin User access only
* This optional description belong to to the group admin.
*/
/**
* @api {get} /user/:id
* @apiPermission admin
*/
For more details, see inherit example.
@apiDeprecated
@apiDeprecated [text]
Mark an API Method as deprecated
Usage: @apiDeprecated use now (#Group:Name).
Example:
/**
* @apiDeprecated
*/
/**
* @apiDeprecated use now (#Group:Name).
*
* Example: to set a link to the GetDetails method of your group User
* write (#User:GetDetails)
*/
@apiDescription
@apiDescription text
Detailed description of the API Method.
Usage: @apiDescription This is the Description.
Example:
/**
* @apiDescription This is the Description.
* It is multiline capable.
*
* Last line of Description.
*/
@apiError
@apiError [(group)] [{type}] field [description]
Error return Parameter.
Usage: @apiError UserNotFound
Example:
/**
* @api {get} /user/:id
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/
@apiErrorExample
@apiErrorExample [{type}] [title]
example
Example of an error return message, output as a pre-formatted code.
Usage: @apiErrorExample {json} Error-Response: This is an example.
Example:
/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
@apiExample
@apiExample [{type}] title
example
Example for usage of an API method. Output as a pre-formatted code.
Use it for a complete example at the beginning of the description of an endpoint.
Usage: @apiExample {js} Example usage: This is an example.
Example:
/**
* @api {get} /user/:id
* @apiExample {curl} Example usage:
* curl -i http://localhost/user/4711
*/
@apiGroup
@apiGroup name
Should always be used.
Defines to which group the method documentation block belongs. Groups will be used for the Main-Navigation in the generated output. Structure definition not need @apiGroup.
Usage: @apiGroup User
Example:
/**
* @api {get} /user/:id
* @apiGroup User
*/
@apiHeader
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
Describe a parameter passed to you API-Header e.g. for Authorization.
Similar operation as @apiParam, only the output is above the parameters.
Usage: @apiHeader (MyHeaderGroup) {String} authorization Authorization value.
Examples:
/**
* @api {get} /user/:id
* @apiHeader {String} access-key Users unique access-key.
*/
@apiHeaderExample
@apiHeaderExample [{type}] [title]
example
Parameter request example.
Usage: @apiHeaderExample {json} Request-Example: { "content": "This is an example content" }
Example:
/**
* @api {get} /user/:id
* @apiHeaderExample {json} Header-Example:
* {
* "Accept-Encoding": "Accept-Encoding: gzip, deflate"
* }
*/
@apiIgnore
@apiIgnore [hint]
Place it on top of a block.
A block with @apiIgnore will not be parsed. It is usefull, if you leave outdated or not finished Methods in your source code and you don't want to publish it into the documentation.
Usage: @apiIgnore Not finished Method
Example:
/**
* @apiIgnore Not finished Method
* @api {get} /user/:id
*/
@apiName
@apiName name
Should always be used.
Defines the name of the method documentation block. Names will be used for the Sub-Navigation in the generated output. Structure definition not need @apiName.
Usage: @apiName GetUser
Example:
/**
* @api {get} /user/:id
* @apiName GetUser
*/
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]
Describe a parameter passed to you API-Method.
Usage: @apiParam (MyGroup) {Number} id Users unique ID.
Examples:
/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
*/
/**
* @api {post} /user/
* @apiParam {String} [firstname] Optional Firstname of the User.
* @apiParam {String} lastname Mandatory Lastname.
* @apiParam {String} country="DE" Mandatory with default value "DE".
* @apiParam {Number} [age=18] Optional Age with default 18.
*
* @apiParam (Login) {String} pass Only logged in users can post this.
* In generated documentation a separate
* "Login" Block will be generated.
*/
@apiParamExample
@apiParamExample [{type}] [title]
example
Parameter request example.
Usage: @apiParamExample {json} Request-Example: { "content": "This is an example content" }
Example:
/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
* {
* "id": 4711
* }
*/
@apiPermission
@apiPermission name
Outputs the permission name. If the name is defined with @apiDefine the generated documentation include the additional title and description.
Usage: @apiPermission admin
Example:
/**
* @api {get} /user/:id
* @apiPermission none
*/
@apiPrivate
@apiPrivate
Defines an API as being private to allow the creation of two API specification documents: one that excludes the private APIs and one that includes them.
Usage: @apiPrivate
Command line usage to exclude/include private APIs: --private false|true
Example:
/**
* @api {get} /user/:id
* @apiPrivate
*/
@apiSampleRequest
@apiSampleRequest url
Use this parameter in conjunction with the apidoc.json configuration parameter sampleUrl.
If sampleUrl is set, all methods will have the api test form (the endpoint from @api will be appended).
Without sampleUrl only methods with @apiSampleRequest will have a form.
if @apiSampleRequest url is set in a method block, this url will be used for the request (it overrides sampleUrl when it starts with http).
If sampleUrl is set and you don't want a method with a test form, then add @apiSampleRequest off to the documentation block.
Usage: @apiSampleRequest http://test.github.com
Examples:
This will send the api request to http://api.github.com/user/:id
Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
*/
This will send the api request to http://test.github.com/some_path/user/:id It overwrites sampleUrl.
Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
* @apiSampleRequest http://test.github.com/some_path/
*/
This will send the api request to http://api.github.com/test/user/:id It extends sampleUrl.
Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
* @apiSampleRequest /test
*/
This will disable the api request for this api-method.
Configuration parameter sampleUrl: "http://api.github.com"
/**
* @api {get} /user/:id
* @apiSampleRequest off
*/
This will send the api request to http://api.github.com/some_path/user/:id It activates the request for this method only, because sampleUrl is not set.
Configuration parameter sampleUrl is not set
/**
* @api {get} /user/:id
* @apiSampleRequest http://api.github.com/some_path/
*/
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]
Success return Parameter.
Usage: @apiSuccess {String} firstname Firstname of the User.
Example:
/**
* @api {get} /user/:id
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/
Example with (group), more group-examples at @apiSuccessTitle:
/**
* @api {get} /user/:id
* @apiSuccess (200) {String} firstname Firstname of the User.
* @apiSuccess (200) {String} lastname Lastname of the User.
*/
Example with Object:
/**
* @api {get} /user/:id
* @apiSuccess {Boolean} active Specify if the account is active.
* @apiSuccess {Object} profile User profile information.
* @apiSuccess {Number} profile.age Users age.
* @apiSuccess {String} profile.image Avatar-Image.
*/
Example with Array:
/**
* @api {get} /users
* @apiSuccess {Object[]} profiles List of user profiles.
* @apiSuccess {Number} profiles.age Users age.
* @apiSuccess {String} profiles.image Avatar-Image.
*/
@apiSuccessExample
@apiSuccessExample [{type}] [title]
example
Example of a success return message, output as a pre-formatted code.
Usage: @apiSuccessExample {json} Success-Response: { "content": "This is an example content" }
Example:
/**
* @api {get} /user/:id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*/
@apiUse
@apiUse name
Include a with @apiDefine defined block. If used with @apiVersion the same or nearest predecessor will be included.
Usage: @apiUse MySuccess
Example:
/**
* @apiDefine MySuccess
* @apiSuccess {string} firstname The users firstname.
* @apiSuccess {number} age The users age.
*/
/**
* @api {get} /user/:id
* @apiUse MySuccess
*/
@apiVersion
@apiVersion version
Set the version of an documentation block. Version can also be used in @apiDefine.
Blocks with same group and name, but different versions can be compared in the generated output, so you or a frontend developer can retrace what changes in the API since the last version.
Usage: @apiVersion 1.6.2
Example:
/**
* @api {get} /user/:id
* @apiVersion 1.6.2
*/
For more watch versioning example.