README

从源代码中的API注释生成Markdown格式的API文档。本版本修复了模板的一些小问题，并添加了几个忽略文件夹。

序言

本文件中所有示例均使用 Javadoc样式（可用于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获取您的项目名称、版本和描述。该文件是可选的（它取决于您的模板是否需要这些数据）。

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 Request User information是必需的，没有@apiapiDoc将忽略文档块。

@apiName必须是一个唯一的名称，并且应该始终使用。格式：方法 + 路径（例如，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.js
• example.js
• apidoc.json

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 (#组:名称).

示例

/**
 * @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 这是描述。

示例

/**
 * @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: 这是示例。

示例

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

@apiExample

@apiExample [{type}] title
            example

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

用于端点描述开头的完整示例。

用法：@apiExample {js} 示例用法：这是示例。

示例

/**
 * @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} 请求示例：{ "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，另一个包含它们。

用法：@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 用户的 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": "这是一个示例内容" }

示例

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

有关更多信息，请参阅 版本控制示例。