README

kleijnweb/php-api-descriptions 的中间件。

组件

DefaultPipe

一个完整的中间件链，可以从开始到结束处理 OpenAPI 请求，一旦添加一些命令处理器。本节中的中间件按顺序执行。

可以追加和前置第三方中间件，ResultSerializer 在调度前追加。

OperationMatcher

确定请求映射到哪个操作对象（路由），或者分别返回 404/405 响应。返回一个请求对象，一些 API 描述对象以及作为属性添加的路由参数。

BodyParsing

解析请求体。在 DefaultPipe 中使用 JsonBodyParser，但解析器是可注入的。

ParameterAssembler

将所有符合 OpenAPI 参数的请求数据（除了主体）强制转换为请求属性。

MessageValidator

使用 OpenAPI 文档验证传入的请求，并在请求无效时返回包含错误信息的 400 响应。

ParameterHydrator

使用 kleijnweb/php-api-hydrator 来填充自定义类型对象和 \DateTime。

CommandDispatcher

简单的命令调度器，按请求中找到的顺序调用 callable。

ResponseBodyDehydrator

拾取 CommandDispatcher 的结果并生成响应对象。

示例

require __DIR__.'/../vendor/autoload.php';

use Doctrine\Common\Cache\ApcuCache;
use KleijnWeb\PhpApi\Descriptions\Description\Repository;
use KleijnWeb\PhpApi\Middleware\DefaultPipe;
use KleijnWeb\PhpApi\Middleware\Tests\Functional\Pet;
use Middlewares\Utils\Factory;
use Zend\Diactoros\Response\SapiEmitter;
use Zend\Diactoros\ServerRequestFactory;

$cache = new ApcuCache();

$commands = [
    '/pets/{id}:get' => function (int $id) use ($cache): Pet {
        return unserialize($cache->fetch($id));
    },
    '/pets:post'     => function (Pet $pet) use ($cache) {
        $count = $cache->fetch('count');
        $pet->setId($id = $count + 1);
        $cache->save($id, serialize($pet));
        $cache->save('count', $id);

        return $pet;
    },
];

$repository = new Repository(null, $cache);
$repository->register(__DIR__.'/../tests/Functional/petstore.yml');

$pipe = new DefaultPipe(
    $repository,
    $commands,
    ['KleijnWeb\PhpApi\Middleware\Tests\Functional']
);

$request = ServerRequestFactory::fromGlobals($_SERVER, $_GET, $_POST, $_COOKIE, $_FILES);

$response = $pipe->dispatch($request, function () {
    return Factory::createResponse(500);
});

(new SapiEmitter())->emit($response);

通过启动开发服务器并发出一些 cURL 请求来验证它是否正常工作

php -S localhost:1234 test.php
curl -vH "Content-Type: application/json" -d '{"name":"doggie"}' https://:1234/pets
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 1234 (#0)
> POST /pets HTTP/1.1
> Host: localhost:1234
> User-Agent: curl/7.47.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 17
> 
* upload completely sent off: 17 out of 17 bytes
< HTTP/1.1 200 OK
< Host: localhost:1234
< Connection: close
< X-Powered-By: PHP/7.0.15-0ubuntu0.16.04.4
< Content-Type: application/json
< Content-Length: 24
< 
* Closing connection 0
{"id":1,"name":"doggie"}

$ curl -vH "Content-Type: application/json" -d '{}' https://:1234/pets
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 1234 (#0)
> POST /pets HTTP/1.1
> Host: localhost:1234
> User-Agent: curl/7.47.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 2
> 
* upload completely sent off: 2 out of 2 bytes
< HTTP/1.1 400 Bad Request
< Host: localhost:1234
< Connection: close
< X-Powered-By: PHP/7.0.15-0ubuntu0.16.04.4
< Content-Type: application/json
< Content-Length: 55
< 
* Closing connection 0
{"errors":{"pet.name":"The property name is required"}}

 curl -v  https://:1234/pets/1
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 1234 (#0)
> GET /pets/1 HTTP/1.1
> Host: localhost:1234
> User-Agent: curl/7.47.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Host: localhost:1234
< Connection: close
< X-Powered-By: PHP/7.0.15-0ubuntu0.16.04.4
< Content-Type: application/json
< Content-Length: 24
< 
* Closing connection 0
{"id":1,"name":"doggie"}

贡献

欢迎拉取请求，但代码必须符合 PSR2 标准，遵循有关参数和返回类型声明的约定，且覆盖率不能下降。

许可证

KleijnWeb\PhpApi\Middleware 在 LGPL，版本 3.0 条款下提供。