README

这是由 @pahanini 创建的 yii2-rest-doc 版本。

#Yii2 Rest 控制器文档生成器

关于

为你的 Yii2 API REST 控制器创建精确的文档。库解析你的代码并生成带有元数据的对象，这些对象可以用于任何模板引擎以生成出色的 API 文档。

当您更改代码时，无需编辑文档。只需使用此工具重新构建文档即可。

安装

将 "pahanini/yii2-rest-doc": "*" 添加到你的 composer.json 中所需部分
添加到你的控制台应用程序配置中

'controllerMap' => [
	'build-rest-doc' => [
		'sourceDirs' => [
			'@frontend\controllers\rest',   // <-- path to your API controllers
		],
		'template' => '//restdoc/restdoc.twig', 
		'class' => '\pahanini\restdoc\controllers\BuildController',
		'sortProperty' => 'shortDescription', // <-- default value (how controllers will be sorted)
		'targetFile' => 'path/to/nice-documentation.html'
	],
]

模板中可用的数据

从代码自动提取的数据列表

控制器名称
每个控制器的操作
模型字段
额外字段
模型规则（待定）

特殊标签列表

控制器的简短和详细描述
查询标签

支持继承。使用 @inherited 或 @inheritdoc 标签。

控制器

@restdoc-ignore - 跳过控制器。
@restdoc-label name - 使用标签标记控制器。标签名称可通过 controller.hasLabel('labelName') 在模板中访问
@restdoc-query name=false Name of part of name to find users - 带有描述的查询参数。

模型

要描述模型的字段，你可以使用两种方法。

链接到属性标签。

如果你已经有了 phpDocumentator @property 标签，你可以使用它来描述 API 字段。模型的文档块示例

/**
 * My model.
 *
 * @property string $title Model's title
 */

@restdoc-link $title - 使用 $title 属性来描述 $title API 字段
@restdoc-link title $model_title - 使用 $title 属性来描述 $model_title API 字段

单独的字段描述

如果你没有 @property 标签或 API 字段没有直接与属性连接，请使用 @restdoc-field 标签。

示例

/**
 * @restdoc-field int $id ID
 * @restdoc-field string $title Model's title
 */

额外字段

使用 @restdoc-extraField 和 @restdoc-extraLink 为额外字段。

排序字段

使用 @restdoc-sortField 根据你的代码排序字段。

与 Slate 集成

Slate 可能是生成良好 API 的最佳工具之一。因此，你可以使用此工具创建 slate 的 index.md 文件。你可以在 afterAction 事件之后自动启动 slate。

示例

'controllerMap' => [
    'build-rest-doc' => [
        'sourceDirs' => [
            '@api/modules/v1/controllers',   // <-- path to your API controllers
        ],
        'template' => '//restdoc/slate.php',
        'class' => '\thiagoarioli\restdoc\controllers\BuildController',
        'targetFile' => '@console/slate/source/index.html.md',
        'on afterAction' => function() {
            exec("bundle exec middleman build");
        }
    ],
]

原因

创建 Yii2 控制器是一个简单的任务，但支持当前状态的文档通常是一个无聊且艰巨的挑战。使用如 phpDocumentator 或 swagger 这样的自动工具可以使生活更轻松，但仍需要使用标签或注释描述所有模型字段和规则。

另一方面，Yii2 控制器和模型保留了很多关于内部结构的信息，如 actions、
字段名称、更新和插入操作的场景。

thiagoarioli / yii2-rest-doc-slade-version

维护者

详细信息