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 中 - https://yiiframework.cn/doc-2.0/yii-rest-urlrule.html 并在 \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数组组成。你必须遵循这些规则来正确定义文档描述和服务测试功能。