README

基于定义的API端点和动作注解的简单文档生成器，适用于Yii2 REST应用。从优秀的 nostop8/yii2-rest-api-doc 衍生。

安装

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

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

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

'modules' => [
  ...
  'documentation' => [
    'class' => fijas\yii2\rest_api_doc\Module',
    //options (not required):
    'layout' => 'default',
    'title' => 'REST API Documentation
  ]
  ...
],

• 在你的应用程序配置文件的 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 等），并向它们添加与为其他操作实现的方式相同的注解。

• 文档是在默认布局中渲染的，可以通过指定 layout 模块选项来更改以满足您的需求。

注解示例

<?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数组组成。您必须遵循这些规则才能正确定义文档描述和服务测试功能。