README

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

安装

• 运行 composer require autoxloo/rest-api-doc;

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

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

'modules' => [
  ...
  'documentation' => 'autoxloo\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 Description：您的端点描述。
2. Rest Fields：['field1', 'field2'] 或 ['field3', 'field4']。（请注意：or 和其后数组是额外的，如果您的服务只接受一种类型的主体，则可能跳过）
3. Rest Filters：['filter1', 'filter2']。
4. Rest Expand：['expandRelation1', 'expandRelation2']。

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

注释示例

<?php

namespace app\controllers;

class ExampleController extends \yii\rest\ActiveController
{

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

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