README

基于定义的API端点和操作注释的简单文档生成器，用于Yii2 REST应用程序。

安装

• 运行 composer require chemezov/yii2-rest-api-doc;

或者，将以下字符串添加到您的composer.json文件的require部分："chemezov/yii2-rest-api-doc": "1.0"，然后运行composer update

• 在您的应用程序配置文件中，在modules部分添加

'modules' => [
  ...
  'documentation' => 'chemezov\yii2\rest_api_doc\Module',
  ...
],

• 在您的应用程序配置文件中，在bootstrap部分添加

'bootstrap' => [
  ...
  'documentation'
  ...
],

请注意。您可以将documentation改为其他任何更适合您REST API名称的词。

• 现在在http://<yourappdomain>/documentation运行您的应用程序，如果您一切都设置正确，您应该会看到类似以下内容：

使用方法

• 首先，您应该知道，此文档生成器仅在您使用以下原则定义REST API端点时才会工作：https://yiiframework.cn/doc-2.0/guide-rest-routing.html
• 目前，您可以为您的端点定义以下注释类型，这些类型将稍后由API文档生成器显示/提供

1. Rest Title: 您的端点标题。
2. Rest Description: 您的端点描述。
3. Rest Fields: ['field1', 'field2'] 或 ['field3', 'field4']。请注意：`or`和其后的数组是可选的，如果您的服务只接受一种类型的body，则可以省略。
4. Rest Filters: ['filter1', 'filter2']。
5. Rest Expand: ['expandRelation1', 'expandRelation2']。

• 如果您正在使用不需要定义端点（因为它们已经在`yii\rest\UrlRule`内部预定义，并在`\yii\rest\ActiveController`中实现）的CRUD服务，并且您仍然想添加一些描述，请定义具有相同名称的空方法（例如actionCreate，actionUpdate等），并像为其他实现的操作一样添加注释。

注释示例

<?php

namespace app\controllers;

/**
 * Rest Title: Example Controller title.
 * Rest Description: Your controller description.
 * Rest Model: app\models\Document.
 */
class ExampleController extends \yii\rest\ActiveController
{

    /**
     * Rest Title: Your endpoint title.
     * Rest Description: Your endpoint description.
     * Rest Fields: ['field1', 'field2'].
     * Rest Filters: ['filter1', 'filter2'].
     * Rest Expand: ['expandRelation1', 'expandRelation2'].
     */
    public function actionTest()
    {
        return ['field1', 'field2'];
    }
}

如您从本例中看到，每个注释都以名称和冒号（`:`）开头，并以句点（`.`）结尾。此外，每个注释类型的主体可能由PHP数组组成。为了正确定义文档描述和服务测试功能，您必须遵循这些规则。