API 说明

API 说明

#jsonapi.org

Discuz! Q 使用的是jsonapi.org (opens new window)定义的格式，使用tobscure/json-api (opens new window)包的实现。

#路由分别对应

以psr-2 基础命名规则外，下面为实践中相关命名规则。
以user 为例，路由和路由名称为小写复数按功能以.分开。
控制器按功能，列表为复数，其它单条担任可为单数驼峰命名。
序列化模型名为单数驼峰命名。
数据库模型以单数驼峰命名。
表名以复数命名。

下面为具体增删改查路由例子：

$route->get('/users', 'users.index', ListUsersController::class);
$route->get('/users/{id}', 'users.resource', ResourceUserController::class);
$route->post('/users', 'users.create', CreateUserController::class);
$route->patch('/users/{id}', 'users.update', UpdateUserController::class);
$route->delete('/users/{id}', 'users.delete', DeleteUserController::class);

#列表数据

继承Discuz\Api\Controller\AbstractListController 需要指定$serializer 要用于序列化模型的data 方法，并实现返回模型集合的方法。该data 方法接收Request 对象和tobscure/json-api Document。

class ListUsersController extends AbstractListController
{
    public $serializer = UserSerializer::class;
    public function data(ServerRequestInterface $request, Document $document)
    {
        return User::all();
    }
}

#单条数据

同列表数据一样继承Discuz\Api\Controller\AbstractResourceController 并实现相关属性和方法，接收参数一样。

class ResourceUserController extends AbstractResourceController
{
    public $serializer = UserSerializer::class;
    public function data(ServerRequestInterface $request, Document $document)
    {
        $body = $request->getQueryParams();
        $id = $body->get('id');
        return User::findOrFail($id);
    }
}

#创建数据

继承Discuz\Api\Controller\AbstractCreateController。这与单条数据相同，但响应状态代码将自动设置为201 Created。您可以通过以下方式访问传入的JSON：API POST传过来的数据可通过$request->getParsedBody() 来取到json 数组，并通过Laravel Arr 类来获取数组相关信息。

class CreateUserController extends AbstractCreateController
{
    public $serializer = UserSerializer::class;
    public function data(ServerRequestInterface $request, Document $document)
    {
        $attributes = Arr::get($request->getParsedBody(), 'data.attributes');
        return User::create([
            'name' => Arr::get($attributes, 'name')
        ]);
    }
}

#更新数据

继承Discuz\Api\Controller\AbstractResourceController 同单条数据一样，现相关属性和方法，接收参数一样，返回相关数据，获取同创建数据一样。

class UpdateUserController extends AbstractCreateController
{
    public $serializer = UserSerializer::class;
    public function data(ServerRequestInterface $request, Document $document)
    {
        $attributes = Arr::get($request->getParsedBody(), 'data.attributes', []);
        $body = $request->getQueryParams();
        $attributes = $body->get('id');
        $user = User::findOrFail($id);
        $user->name = $attributes['name'];
        $user->save();
        return $user;
    }
}

#删除数据

继承Discuz\Api\Controller\AbstractDeleteController 实现delete 方法，该方法接收Request，默认返回空204 No Content 响应。

class DeleteUserController extends AbstractDeleteController
    public function delete(ServerRequestInterface $request)
    {
        $id = Arr::get($request->getQueryParams(), 'id');
        User::findOrFail($id)->delete();
    }
}

#序列化模型说明

继承Discuz\Api\Serializer\AbstractSerializer 实现getDefaultAttributes 方法，该方法接收数据库模型，写好type 属性。

class UserSerializer extends AbstractSerializer
{
    protected $type = 'user';
    public function getDefaultAttributes($model)
    {
        return [
            'id' => $model->id,
            'username' => $model->username,
            'email' => $model->email
        ];
    }
}

#自定义返回类型

实现接口Psr\Http\Server\RequestHandlerInterface。

<?php
namespace Discuz\Api\Controller;
use Psr\Http\Server\RequestHandlerInterface;
class AbstractSerializeController implements RequestHandlerInterface
{
public function handle(ServerRequestInterface $request): ResponseInterface
{
        return new HtmlResponse();
    }
}