README

创建一个期望请求体为 Json 的路由，将此请求体与路由提供的 Json schema 进行检查，并将顶级参数传递给操作。

ApiJsonRouter 扩展了 Contributte api-router，因此请参阅完整路由定义的文档。

Opis JSON Schema 用于完整的 Json Schema 标准验证。

默认使用 "draft-2020-12" 标准进行验证。

安装

composer require adt/api-json-router

示例

路由器

final class RouterFactory
{
    // Prepare your route specification
    public static function getApiRouteSpecification(): array 
    {
		return [
			'/api/devices>POST' => [
				'path' => '/api/devices/<uuid>/request',
				'presenter' => 'DeviceRequest',
				'method' => 'POST',
				'action' => 'create',
				'parameters' => [
					'uuid' => ['type' => 'string', 'requirement' => '.+'],
				],
				'body' => [
					'type' => 'object',
					'properties' => [
						'type' => ['type' => 'string'],
					],
					'required' => ['type']
				],
				'title' => 'Create a request',
				'description' => 'Create a request for a specific device.',
		    ]
	    ];
    }

    // Create API router
    public static function createRouter(): \ADT\ApiJsonRouter\ApiRouteList
    {
        $apiRouter = new \ADT\ApiJsonRouter\ApiRouteList('Api');
        $apiRouter->addRoutesBySpecification(self::getApiRouteSpecification());
        return $apiRouter;
    }
}

设备请求演示者

class DeviceRequestPresenter extends Presenter 
{
    public function actionCreate(string $uuid, string $_type) 
    {
        // Check if you have access to a specific device
        if ($this->deviceQuery->create()->byUuid($uuid)) {
            $this->sendJsonError(404);
        }
    
        // Create a device request
        $deviceRequest = new DeviceRequest($device, $_type)
        $this->em->persist();
        $this->em->flush();
        
        // Send a response
        $this->sendJson(['uuid' => $deviceRequest->getUuid(), 'type' => $device->getType()]);
    }
}

文档演示者

class DocsPresenter extends Presenter
{
	public function actionDefault()
	{
		// Generate API documentation in Markdown format
		$apiDocumentation = new ADT\ApiJsonRouter\ApiDocumentation('API Docs', RouterFactory::getApiRouteSpecification());
		$markdownApiDocumentation = $apiDocumentation->getDocumentation();

		// Generate API documentation in HTML format
		// e.g. you can use https://github.com/erusev/parsedown
		die((new \Parsedown())->text($markdownApiDocumentation));
	}
}

错误演示者

class ErrorPresenter extends Presenter
{
	public function renderDefault(Exception $exception)
	{
		if ($exception instanceof ApiException) {
		    $this->sendJsonError($exception->getCode(), $exception->getMessage());
		}

		Debugger::log($exception, ILogger::EXCEPTION);

		$this->sendJsonError(500, 'There was an error processing your request. Please try again later.');
	}
}