README

从源代码中的API注释生成Markdown格式的API文档。

前言

本文档中的所有示例均使用 Javadoc-Style (可用于C#、Go、Dart、Java、JavaScript、PHP、TypeScript以及所有其他支持Javadoc的语言)

/**
 * This is a comment.
 */

安装

composer global require lincanbin/apidoc-markdown:~1.0

运行

apidoc-markdown -i myapp/ -o apidoc/

或

apidoc -i myapp/ -o apidoc/

在 myapp/ 目录内创建所有文件的apiDoc，并将所有输出放置到 apidoc/ 目录中。

如果没有参数，apiDoc将从当前目录（包括子目录）中的所有 .cs .dart .erl .go .java .js .php .py .rb .ts 文件生成文档，并将输出写入 ./apidoc/。

命令行界面

显示命令行参数

apidoc-markdown -h

重要参数

配置（apidoc.json）

项目根目录中的可选 apidoc.json 包含关于您的项目的常见信息，例如标题、简短描述、版本和配置选项，如页眉/页脚设置或特定模板的选项。

apidoc.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}

如果您使用 package.json（例如，在Node.js项目中），所有 apidoc.json 设置也可以在 package.json 中完成，只需将其添加到 "apidoc": { } 参数下即可。

package.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "apidoc": {
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1"
  }
}

apidoc.json 设置

特定模板设置

以下设置是针对apiDoc默认模板的。

页眉/页脚

在您的项目的 apidoc.json 中，您可以添加页眉和页脚。

标题将在导航中可见。文件名应该是Markdown文本文件。

apidoc.json

{
  "header": {
    "title": "My own header title",
    "filename": "header.md"
  },
  "footer": {
    "title": "My own footer title",
    "filename": "footer.md"
  }
}

基本

在这个基本示例中，我们有一个小的项目文件和一个apidoc.json。

查看示例输出

apidoc.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "A basic apiDoc example"
}

从 apidoc.json 中，apiDoc获取您项目的名称、版本和描述。该文件是 optional（是否需要这些数据取决于您的模板）。

example.js

/**
 * @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"
 *     }
 */

文档块以 /** 开始，以 */ 结束。

此示例描述了一个通过用户的 id 请求用户信息的 GET 方法。

@api {get} /user/:id 请求用户信息 是必需的，没有 @apiapiDoc会忽略文档块。

@apiName 必须是一个唯一的名称，并且始终应该使用。格式：method + path（例如，Get + User）

@apiGroup 应始终使用，并用于将相关API分组在一起。

所有其他字段都是可选的，请参阅它们的描述，见 apiDoc-Params。

继承

使用继承，您可以定义可重用的文档片段。

查看示例输出

apidoc.json

{
  "name": "example-inherit",
  "version": "0.1.0",
  "description": "apiDoc inherit example"
}

example.js

/**
 * @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
 */

在这个例子中，使用 @apiDefine 定义了一个名为 UserNotFoundError 的块。该块可以用 @apiUse UserNotFoundError 多次使用。

在生成的输出中，GET 和 PUT 方法都将有完整的 UserNotFoundError 文档。

要定义一个继承块，请使用 apiDefine。要引用一个块，请使用 apiUse。 apiGroup 和 apiPermission 是使用命令，但在它们的上下文中，不继承参数，只有标题和描述（结合使用apiVersion）。

继承只能有一个父级，更多级别会使内联代码难以阅读且更改非常复杂。

版本控制

apiDoc提供的一个有用功能是能够维护API所有历史版本和最新版本的文档。这使得比较方法版本与其前辈成为可能。前端开发者可以轻松地看到发生了什么变化，并相应地更新他们的代码。

查看示例输出

在示例中，点击右上角的下拉框（主要版本）并选择与前辈比较所有版本。

主要导航栏用绿色条标记所有更改的方法。
每个方法都会显示与其前辈相比的实际差异。
绿色标记表示添加的内容（在本例中，标题文本已更改，并添加了字段registered）。
红色标记表示删除的内容。

您可以将主要版本（右上角）更改为之前的版本，并比较旧方法与其前辈。

apidoc.json

{
  "name": "example-versioning",
  "version": "0.2.0",
  "description": "apiDoc versioning example"
}

为了避免随着时间的推移API文档更改时代码膨胀，建议使用一个名为_apidoc.js的单独历史文件。在更改文档块之前，将旧文档复制到该文件中，apiDoc将自动包含历史信息。

_apidoc.js

/**
 * @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（您的当前项目文件）

/**
 * @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"
 *     }
 */

重要的是在每个文档块上设置@apiVersion版本。

版本可以用于每个块，也可以用于继承块。您不需要更改继承块上的版本，解析器会自动检查最近的前辈。

完整示例

这是一个复杂的示例，包括继承、版本化文件和历史文件_apidoc.js，解释包含在代码和生成的文档中。

查看示例输出

文件

apiDoc-Params

结构化参数，例如

@apiDefine

用于定义可重用的文档块。此块可以包含在常规API文档块中。使用@apiDefine可以帮助您更好地组织复杂的文档，并避免重复块。

定义的块可以包含所有参数（如@apiParam），但不能包含其他定义的块。

@api

@api {method} path [title]

必需！

如果没有此指示器，apiDoc解析器将忽略文档块。

唯一的例外是@apiDefine定义的文档块，它们不需要@api。

用法：@api {get} /user/:id Users unique ID.

示例

/**
 * @api {get} /user/:id
 */

@apiDefine

@apiDefine name [title]
                     [description]

定义一个要嵌入到@api块中或到API函数（如@apiPermission）中的文档块。

@apiDefine在每个块中只能使用一次

使用@apiUse导入定义的块，或者使用名称使用标题和描述。

用法：@apiDefine MyError

示例

/**
 * @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
 */

有关更多详细信息，请参阅继承示例。

@apiDeprecated

@apiDeprecated [text]

标记API方法为已弃用

用法：@apiDeprecated use now (#Group:Name).

示例

/**
 * @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

API方法的详细描述。

用法：@apiDescription This is the Description.

示例

/**
 * @apiDescription This is the Description.
 * It is multiline capable.
 *
 * Last line of Description.
 */

@apiError

@apiError [(group)] [{type}] field [description]

错误返回参数。

用法：@apiError UserNotFound

示例

/**
 * @api {get} /user/:id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

@apiErrorExample

@apiErrorExample [{type}] [title]
                 example

错误返回消息的示例，以预格式化代码输出。

用法：@apiErrorExample {json} Error-Response: This is an example.

示例

/**
 * @api {get} /user/:id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

@apiExample

@apiExample [{type}] title
            example

API方法的用法示例。以预格式化代码输出。

在端点的描述的开始使用它以提供一个完整的示例。

用法：@apiExample {js} Example usage: This is an example.

示例

/**
 * @api {get} /user/:id
 * @apiExample {curl} Example usage:
 *     curl -i https:///user/4711
 */

@apiGroup

@apiGroup name

应该始终使用。

定义方法文档块所属的组。组将在生成的输出中的主导航中使用。结构定义不需要@apiGroup。

用法：@apiGroup User

示例

/**
 * @api {get} /user/:id
 * @apiGroup User
 */

@apiHeader

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

描述传递给您的API-Header的参数，例如授权。

与@apiParam类似的操作，只是输出在参数之上。

用法：@apiHeader (MyHeaderGroup) {String} authorization 授权值。

示例

/**
 * @api {get} /user/:id
 * @apiHeader {String} access-key Users unique access-key.
 */

@apiHeaderExample

@apiHeaderExample [{type}] [title]
                   example

参数请求示例。

用法：@apiHeaderExample {json} Request-Example: { "content": "This is an example content" }

示例

/**
 * @api {get} /user/:id
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Accept-Encoding": "Accept-Encoding: gzip, deflate"
 *     }
 */

@apiIgnore

@apiIgnore [hint]

将其放置在块顶部。

带有@apiIgnore的块将不会被解析。如果您的源代码中留有过时或未完成的方法，并且您不希望将其发布到文档中，这很有用。

用法：@apiIgnore 未完成的方法

示例

/**
 * @apiIgnore Not finished Method
 * @api {get} /user/:id
 */

@apiName

@apiName name

应该始终使用。

定义方法文档块的名称。名称将被用于生成的输出中的子导航。不需要@apiName结构定义。

用法：@apiName GetUser

示例

/**
 * @api {get} /user/:id
 * @apiName GetUser
 */

@apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]

描述传递给API方法的参数。

用法：@apiParam (MyGroup) {Number} id 用户唯一ID。

示例

/**
 * @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

参数请求示例。

用法：@apiParamExample {json} Request-Example: { "content": "This is an example content" }

示例

/**
 * @api {get} /user/:id
 * @apiParamExample {json} Request-Example:
 *     {
 *       "id": 4711
 *     }
 */

@apiPermission

@apiPermission name

输出权限名称。如果使用@apiDefine定义了名称，则生成的文档将包括额外的标题和描述。

用法：@apiPermission admin

示例

/**
 * @api {get} /user/:id
 * @apiPermission none
 */

@apiPrivate

@apiPrivate

定义一个API作为私有API，允许创建两个API规范文档：一个不包括私有API的文档，另一个包括私有API的文档。

用法：@apiPrivate

命令行用法以排除/包含私有API：--private false|true

示例

/**
 * @api {get} /user/:id
 * @apiPrivate
 */

@apiSampleRequest

@apiSampleRequest url

将此参数与apidoc.json配置参数sampleUrl结合使用。

如果设置了sampleUrl，则所有方法都将有API测试表单（来自@api的端点将被附加）。如果没有设置sampleUrl，则只有带有@apiSampleRequest的方法才有表单。

如果在方法块中设置了@apiSampleRequest url，则将使用此url进行请求（如果它以http开头，则它将覆盖sampleUrl）。

如果设置了sampleUrl并且您不希望方法有测试表单，则在文档块中添加@apiSampleRequest off。

用法：@apiSampleRequest http://test.github.com

示例

这将向http://api.github.com/user/:id发送API请求

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 */

这将向http://test.github.com/some_path/user/:id发送API请求，它将覆盖sampleUrl。

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://test.github.com/some_path/
 */

这将向http://api.github.com/test/user/:id发送API请求，它扩展了sampleUrl。

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest /test
 */

这将禁用此API方法的API请求。

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest off
 */

这将向http://api.github.com/some_path/user/:id发送API请求，因为它只激活了此方法的请求，因为sampleUrl未设置。

Configuration parameter sampleUrl is not set
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://api.github.com/some_path/
 */

@apiSuccess

@apiSuccess [(group)] [{type}] field [description]

成功返回参数。

用法：@apiSuccess {String} firstname 用户名。

示例

/**
 * @api {get} /user/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

用法示例（带(group)），更多组示例请参阅@apiSuccessTitle

/**
 * @api {get} /user/:id
 * @apiSuccess (200) {String} firstname Firstname of the User.
 * @apiSuccess (200) {String} lastname  Lastname of the User.
 */

用法示例（对象）

/**
 * @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.
 */

用法示例（数组）

/**
 * @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

成功返回消息的示例，以预格式化代码输出。

用法：@apiSuccessExample {json} Success-Response: { "content": "This is an example content" }

示例

/**
 * @api {get} /user/:id
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 */

@apiUse

@apiUse name

包含使用@apiDefine定义的块。如果与@apiVersion一起使用，则将包含相同的或最近的先前的版本。

用法：@apiUse MySuccess

示例

/**
 * @apiDefine MySuccess
 * @apiSuccess {string} firstname The users firstname.
 * @apiSuccess {number} age The users age.
 */

/**
 * @api {get} /user/:id
 * @apiUse MySuccess
 */

@apiVersion

@apiVersion version

设置文档块的版本。版本也可以用于 @apiDefine。

具有相同组和名称，但版本不同的块可以在生成的输出中进行比较，因此您或前端开发者可以回溯自上次版本以来API中的更改。

用法：@apiVersion 1.6.2

示例

/**
 * @api {get} /user/:id
 * @apiVersion 1.6.2
 */

更多信息请查看版本示例。

lincanbin / apidoc-markdown

维护者

详细信息

README

前言

安装

运行

命令行界面

配置（apidoc.json）

apidoc.json 设置

特定模板设置

页眉/页脚

基本

继承

版本控制

完整示例

apiDoc-Params

@api

@apiDefine

@apiDeprecated

@apiDescription

@apiError

@apiErrorExample

@apiExample

@apiGroup

@apiHeader

@apiHeaderExample

@apiIgnore

@apiName

@apiParam

@apiParamExample

@apiPermission

@apiPrivate

@apiSampleRequest

@apiSuccess

@apiSuccessExample

@apiUse

@apiVersion