README

Yii2 JSON API。

需求

Yii2
ext-shared-components

安装

使用 composer 并在您的 composer.json 文件中添加以下行

"futuretek/yii2-api": "*"

变更日志

v1.0.0

首次发布

使用

在控制器初始化方法中设置 API

	public function init()
	{
		$this->setIdentity(UserModel);
		parent::init();
	}

定义自定义操作

public function actions()
{
    return [
        ...,
        'myAction' => [
            'class' => 'futuretek\api\ApiAction',
        ],
        ...,
    ];
}

将 phpDoc 标签（见下文）添加到您希望文档化的操作中

/**
* Returns hello and the name that you gave
*
* @param string $name Your name
* @return string
* @api
*/
public function getHello($name)
{
    return ['hello' => 'Hello ' . $name];
}

可选地使用 IpFilter 限制对 API 的访问。在控制器类的 behaviors() 方法中声明。

public function behaviors()
{
    return [
        'ips' => [
            'class' => \futuretek\api\IpFilter::className(),
            'policy' => IpFilter::POLICY_ALLOW_ALL,
            'list' => [
                '192.168.1.2',
                '192.168.11.1-192.168.11.27',
                '10.*.*.*',
                '172.16.1.0/24',
            ],
        ],
    ];
}

内置方法

ping

ping 操作主要用于测试 API 接口可用性

generate-definition

生成 API 方法定义列表

如果没有指定 API 方法，这是默认操作

generate-confluence-documentation

生成 API 文档的 Confluence 标记

允许的 phpDoc 标签

@param

用法：@param type $variable description {additional parameters}

指示输入变量。如果输入变量是数组，可以使用 [] 定义它，例如 String[]

附加参数

可选地，可以为每个 @param 标签定义额外的属性，方法是将定义括在花括号内，并用逗号分隔，如下所示

{[attribute1 = value1][, attribute2 = value2], ...}

其中属性可以是以下之一

validate - 指定用于检查参数值的验证器函数

验证器必须是 Validate 类的静态方法名称。

isInt
isString

element - 数组元素定义。如果 @param 是 Array 类型，可以使用此属性描述数组元素

用法：{element=name|type|description, element=name|type, ...}

@return

用法：@return type description

指示方法返回值。如果返回值是数组，可以使用 [] 定义它，例如 String[]

注意： API 函数应始终（我指的是始终！）返回关联数组。如果返回其他类型，则视为函数没有输出。此外，如果函数返回布尔 false（或可以转换为 false 的其他数据类型），API 调用将导致一般错误消息。

如果要在方法内部表达处理失败，应抛出异常。

@return-param

用法：@return-param type name description

所有 API 方法必须返回 Array、bool 或 void（null）。在 Array 的情况下，可以使用此标签指定每个数组元素。这主要是为了描述方法。此标签不绑定任何附加逻辑。

@api

用法：@api

表示此方法应通过 API 接口访问。未使用此标签的方法将被忽略。

@no-auth

用法：@no-auth

表示此方法将公开访问，无需用户身份验证

@permission

用法：@permission permissionName

运行操作需要指定的 RBAC 权限。如果使用 @no-auth，则忽略此标签

@transaction

用法：@transaction

在数据库事务中运行方法

futuretek / yii2-api

维护者

详情