README

关于

为您的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'
	],
]

模板示例（twig）

{% for controller in controllers %}
	<h2>{{ controller.shortDescription }}</h2>
	<p>{{ controller.longDescription }}</p>
	{% if controller.hasLabel('authenticated') %}
		<div class="warning">Require login and password!</div>
	{% endif %}
	<p>List of supported actions:
		<ul>
			{% for action in controller.actions %}
				<li>{{ action }}</li>
			{% endfor %}
		</ul>
	</p>
	<p>Get params available for index action:</p>
		<ul>
			{% for item in controller.query %}
				<li>
					<b>{{ item.variableName }}</b> - {{ item.description }}, default - {{ item.defaultValue }}
				</li>
			{% endfor %}
		</ul>
	</p>
	<p>Model fields:</p>
	<table>
		<tr>
			<th>Name</th>
			<th>Type</th>
			<th>Description</th>
			<th>Can be updated?</th>
		</tr>
		{% for item in controller.model.fields %}
			<tr>
				<td>{{ item.name }}</td>
				<td>{{ item.type }}</td>
				<td>{{ item.description }}</td>
				<td>{{ item.isInScenario('api-update')  ? 'yes' : 'no' }}</td>
			</tr>
		{% endfor %}
	</table>
{% endfor %}

模板中可用的数据

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

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

特殊标签列表

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

支持继承。使用 @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 根据您的代码排序字段。

跳过字段

使用 @restdoc-ignore 跳过字段。

/**
 * @restdoc-ignore $hidden
 */

与Slate集成

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

示例

'controllerMap' => [
	'build-rest-doc' => [
		'sourceDirs' => [
			'@frontend\controllers\rest',
		],
		'template' => '//restdoc/restdoc.twig',
		'class' => '\pahanini\restdoc\controllers\BuildController',
		'targetFile' => 'path/to/slate/index.md',
		'on afterAction' => function() { exec("bundle exec middleman build") }
	],
]

理由

创建Yii2控制器是一项简单任务，但支持文档在现实状态中通常是枯燥且具有挑战性的。使用自动工具如 phpDocumentator 或 swagger 可以使生活更容易，但仍需要使用标签或注释描述所有模型字段和规则。

另一方面，Yii2控制器和模型保留了许多有关内部结构的信息，例如操作、字段名称、更新和插入操作的场景。
此包从REST控制器和模型中提取此类信息，并使用这些数据以及phpdocumentator标签自动生成slate或任何其他文档文件的index.md。