README

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

安装

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

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

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

'modules' => [
  ...
  'documentation' => 'nostop8\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数组组成。您必须遵循这些规则才能正确定义文档描述和功能测试。

额外技巧

在开发需要依赖于尚未提供的第三方服务（由于某种原因）的API时，使用外部 在线API模拟工具 - QuickMocker 可能很有用。当您将应用程序与webhooks集成并需要调试来自某些第三方服务而您又不远程托管应用程序时，它也非常有用。