README

此库提供了定义 REST API 以及验证请求和响应的所有工具。

安装

composer require everlution/simple-rest-api

# if you are using the JsonSchemaValidator
composer require justinrainbow/json-schema

API 定义

为了定义一个新的 API，您需要实现 Everlution\SimpleRestApi\Api\ApiInterface。

如果您要实现一个将使用 JSON Schema 进行验证的 API，您可以实现 JsonSchemaApiInterface。

<?php

namespace App\Api\Sms;

use App\ApiBusinessLogic\Sms\SendApiBusinessLogic;
use App\JsonSchema\Api\Sms\Send\RequestJsonSchema;
use App\JsonSchema\Api\Sms\Send\ResponseJsonSchema;
use Everlution\SimpleRestApi\Api\AbstractApi;
use Everlution\SimpleRestApi\Api\JsonSchemaApiInterface;
use Everlution\SimpleRestApi\ApiRequestHandler\DefaultApiRequestHandler;
use Everlution\SimpleRestApi\ApiValidator\JsonSchemaApiValidator;
use Symfony\Component\HttpFoundation\Request;

class SendApi extends AbstractApi implements JsonSchemaApiInterface
{
    private $requestJsonSchema;

    private $responseJsonSchema;

    public function __construct(
        JsonSchemaApiValidator $apiValidator,
        DefaultApiRequestHandler $apiRequestHandler,
        SendApiBusinessLogic $apiBusinessLogic,
        RequestJsonSchema $requestJsonSchema,
        ResponseJsonSchema $responseJsonSchema
    ) {
        parent::__construct($apiValidator, $apiRequestHandler, $apiBusinessLogic);

        $this->requestJsonSchema = $requestJsonSchema;
        $this->responseJsonSchema = $responseJsonSchema;
    }

    public function getTitle(): string
    {
        return 'SMS Send';
    }

    public function isDeprecated(): bool
    {
        return false;
    }

    public static function getMethods(): array
    {
        return [Request::METHOD_POST];
    }

    public static function getRoutesPaths(): array
    {
        return [
            '/sms/send',
        ];
    }

    public function isEnabled(): bool
    {
        return true;
    }

    public function getStatusCodes(): array
    {
        return parent::getStatusCodes() + [401 => 'Unauthorized'];
    }

    public function getRequestJsonSchema(): string
    {
        return $this->requestJsonSchema->generate();
    }

    public function getResponseJsonSchema(): string
    {
        return $this->responseJsonSchema->generate();
    }
}

API 请求处理器

这是负责验证请求和响应并执行业务逻辑的服务。库提供了一个默认处理器 Everlution\SimpleRestApi\ApiRequestHandler\DefaultApiRequestHandler。

API 验证

<?php

namespace App\JsonSchema\Api\Sms\Send;

class RequestJsonSchema
{
    public function toArray(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'number' => [
                    'type' => 'string',
                    'description' => 'The phone number',
                ],
                'text' => [
                    'type' => 'string',
                    'description' => 'The content of the message',
                    'maxLength' => 255
                ]
            ]
        ];
    }
    
    public function generate(): string
    {
        return json_encode($this->toArray());
    }
}

API 业务逻辑

这是定义 API 应该做什么的服务。

<?php

namespace App\ApiBusinessLogic\Sms;

use Everlution\SimpleRestApi\Api\ApiInterface;
use Everlution\SimpleRestApi\ApiBusinessLogic\ApiBusinessLogicInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class SendApiBusinessLogic implements ApiBusinessLogicInterface
{
    public function execute(ApiInterface $api, Request $request): Response
    {
        // Logic here
    }
}

同样适用于响应 JSON Schema

如何与框架集成

Symfony 4

将此文件添加到 config/routes.php

<?php

use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
use App\Api\Sms;

$apis = [
    Sms\SendApi::class,
    // ... other APIs
];

return function (RoutingConfigurator $routes) use ($apis) {
    foreach ($apis as $api) {
        $i = 0;
        foreach ($api::getRoutesPaths() as $routePath) {
            $pathName = sprintf('%s_%s', str_replace('\\', '_', $api), $i);
            $routes
                ->add($pathName, $routePath)
                ->controller([$api, 'sendResponse'])
                ->methods($api::getMethods());

            $i++;
        }
    }
};

然后，您需要将此添加到 config/services.yaml 以使框架识别 API 作为控制器。

_instanceof:
    Everlution\SimpleRestApi\Api\ApiInterface:
    tags: ['controller.service_arguments']