README

yii2 api项目根据逻辑生成文档

Installation

你可以通过 composer进行安装.

执行安装：

php composer.phar require --prefer-dist rockyfc/yii2-smart-apidoc "*"

或者把如下代码加到composer.json文件中去，然后再执行安装

"rockyfc/yii2-smart-apidoc": "*"

使用方法

你可以将如下代码放到main-local.php中去：

if (!YII_ENV_TEST) {
 
    //other code ...

    $config['modules']['doc'] = [
        'class' => 'smart\apidoc\Module',
        
        //是否载入yii2-smart-apidoc文档提供的README.md文件，默认是true
        'loadSmartReadmeFile' => true,
        
        //当前api项目中的自定义的README.md文件绝对路径
        //'readMeFilePath' => '@webroot/../README.md',
        
        
        //要屏蔽掉的Module模块
        'skipModulesId' => ['debug', 'gii', 'doc'],
        
        //数据对象的命名空间。
        //对应着文档中的对象列表，这个配置关乎着是否在接口文档中体现对象列表
        'entitiesNamespace' => [
            //'api\common\models'
        ]
    ];
    
    //other code ...
}

或者，你也可以把他直接放到main.php中去，但是不建议这么做，除非接口文档可以对外公开：

'modules' => [
        //other code ...
        
        //文档模块的配置
        'doc' => [
                    'class' => 'smart\apidoc\Module',
        
                    //是否载入yii2-smart-apidoc文档提供的README.md文件，默认是true
                    'loadSmartReadmeFile' => true,
                            
                    //当前api项目中的自定义的README.md文件绝对路径
                    //'readMeFilePath' => '@webroot/../README.md',
        
                    //要屏蔽掉的Module模块
                    'skipModulesId' => ['debug', 'gii','doc'],
        
                    //数据对象的命名空间。
                    //对应着文档中的对象列表，这个配置关乎着是否在接口文档中体现对象列表
                    'entitiesNamespace' => [
                        //'api\common\models'
                    ]
                ],
        
        //other code ...
    ],

生成文档要求你的接口代码符合以下几个条件：

推荐你尽可能使用Yii2框架在yii\rest\ActiveController::actions()提供的系统接口 index、view、create、delete、update接口;
或者你也可以通过继承IndexAction、ViewAction、CreateAction、UpdateAction、DeleteAction类来实现自定义的Action类，并在actions函数里面引用他。
该接口文档推荐按照Module的方式来书写接口。
你也可以在yii\rest\ActiveController的子类里面自定义接口。但是需要在接口的注释里面添加一个@modelClass标签来告诉文档系统，你自己写的接口引用的是哪个model类。就像以下代码：

class ExampleController extends yii\rest\ActiveController{
        
       //other code ...
    
       /**
        * 我是一个接口示例。
        *
        * @modelClass \api\modules\v1\models\TestModel
        * @return mixed
        */
       public function actionTest(){
           $model = new \api\modules\v1\models\TestModel;
           $model->load(\Yii::$app->request->post(),'');
           $model->save(true);
           return $model;
       }
    
    //other code ...
    
}

注意：@modelClass 请写一个带有完整命名空间的model类。例如：\api\modules\v1\models\TestModel 当然，你也可以不写@modelClass标签，如果不写的话，会取当前Controller类中设置的$modelClass。并且，在接口的注释里面，你还应该添加一个@scenario标签，来告诉文档，当前接口用的是什么场景，如果不写的话，取yii\base\Model::SCENARIO_DEFAULT设置的默认场景。

class ExampleController extends yii\rest\ActiveController{
        
       //other code ...
    
       /**
        * 我是一个接口示例。
        *
        * @modelClass \api\modules\v1\models\TestModel 
        * @scenario test
        * @return mixed
        */
       public function actionTest(){
           $model = new \api\modules\v1\models\TestModel([
               'scenario' => 'test'//设置场景
           ]);
           $model->load(\Yii::$app->request->post(),'');
           $model->save(true);
           return $model;
       }
    
    //other code ...
    
}

如果某一个接口类或者接口类中某一个action不想在接口文档中呈现，请在类的注释中添加"@disabled"标签。比如：

/**
 * 我是一个测试接口类
 * @disabled
 */
class DefaultController extends Controller
{
    //code ...
}

或者

/**
 * 我是一个测试接口类
 */
class DefaultController extends Controller
{
    //code ...
    
   /**
    * 我是一个测试接口
    * @disabled
    */
    public function actionTest(){
    
    }
    
    //code ...
}

请看下面的完整示例：

    /**
     * 我是一个接口示例
     *
     * 这样的接口写法虽不推荐，但是日常开发过程中，不可避免的会采用这种写法，所以，如果遇到开发者自己开发action接口的话，注释内容便成了生成
     * 文档的关键。所以，对于一个接口请求，定位资源的url里面如果有参数的话，请在action函数添加上相应的参数，并且参数的注释内容按照如下格
     * 式定义即可：
     * range(1,2)表示status字段的可选值；
     * default(1)表示如果用户不传参数的话，status字段取默认值1。
     * required关键字表示此字段必填。
     * 调用此接口的url可能会这样写 "http://xxx.com/v1/activity/edit-data?id=xx&status=1"
     *
     * @param int $status 状态值，range(1,2)，default(1)
     * @param int $userId 用户ID，required
     *
     * @modelClass \api\modules\v1\models\ActivitySearch
     * @scenario edit
     *
     * @return null|\api\modules\v1\models\ActivitySearch
     */
    public function actionEditData(int $status = 1, int $userId)
    {
        $model = \api\modules\v1\models\ActivitySearch::findOne([
            'status' => $status,
            'user_id' => $userId
        ]);
        $model->setScenario('edit'); //如果不设置，默认使用default场景
        $model->load(\Yii::$app->request->post(), '');
        $model->save(true);
        return $model;
    }

对于一些get请求，如果用户需要输入一些查询条件才能获取到数据的话，为了保持与actions方法中定义的index接口或者view接口的url相一致的写法，可以在注释中添加@options标签。比如自定义一个list接口

  /**
     * 我是一个接口示例
     *
     * 为了让自定义的接口也支持fields、filter、expand写法，可以在注释中添加@scenario标签，标签可选值为fields、filter、expand
     * 调用此接口的url可能会这样写 "http://api.localhost/content/index?fields=username,id&filter[status]=1&filter[user_id]=xxx&expand=user,messages"
     *
     * @modelClass \api\modules\v1\models\ActivitySearch
     * @scenario list
     * @options filter,expand,fields
     * @return null|\api\modules\v1\models\ActivitySearch
     */
    public function actionList()
    {
        $model = new \api\modules\v1\models\ActivitySearch();
        $model->setScenario('list'); //如果不设置，默认使用default场景
        $model->load(\Yii::$app->request->post(), 'filter');
        $model->search();
        return $model;
    }

对于本文档的使用，以及yii2 restful接口的详细用法，可以参见视频： Yii2 Restful Api视频：https://edu.csdn.net/course/detail/26600

rockyfc / yii2-smart-apidoc

Maintainers

Details

README

Installation

使用方法