README

理解重要事项

• OpenAPI 规范

安装

composer require 'sunrise/http-router-openapi:^2.1'

快速入门

use Psr\SimpleCache\CacheInterface;
use Sunrise\Http\Router\OpenApi\Object\Info;
use Sunrise\Http\Router\OpenApi\OpenApi;
use Sunrise\Http\Router\OpenApi\RouteInterface;

$openapi = new OpenApi(new Info('Acme', '1.0.0'));

// Passing PSR-16 cache to the openapi object:
/** @var CacheInterface $cache */
$openapi->setCache($cache);

// Passing all routes to the openapi object:
/** @var RouteInterface[] $routes */
$openapi->addRoute(...$routes);

// When using Sunrise Router:
/** @var \Sunrise\Http\Router\Router $router */
$openapi->addRoute(...$router->getRoutes());

构建 OpenAPI 文档

// Converting the openapi object to JSON document:
$openapi->toJson();
// Converting the openapi object to YAML document:
$openapi->toYaml();
// Converting the openapi object to an array:
$openapi->toArray();

构建 JSON 架构

将操作部分转换为 JSON Schema。

$openapi->getRequestCookieJsonSchema();
$openapi->getRequestHeaderJsonSchema();
$openapi->getRequestQueryJsonSchema();
$openapi->getRequestBodyJsonSchema();
$openapi->getResponseBodyJsonSchema();

PSR-15 中间件

RequestValidationMiddleware

使用路由描述验证请求。

use Sunrise\Http\Router\OpenApi\Middleware\RequestValidationMiddleware;
use Sunrise\Http\Router\OpenApi\OpenApi;

/** @var OpenApi $openapi */
$middleware = new RequestValidationMiddleware($openapi);

Symfony 命令

GenerateOpenapiDocumentCommand

生成 OpenAPI 文档。

use Sunrise\Http\Router\OpenApi\Command\GenerateOpenapiDocumentCommand;
use Sunrise\Http\Router\OpenApi\OpenApi;

/** @var OpenApi $openapi */
$command = new GenerateOpenapiDocumentCommand($openapi);

php bin/app router:generate-openapi-document --help

GenerateJsonSchemaCommand

生成操作部分到 JSON Schema。

use Sunrise\Http\Router\OpenApi\Command\GenerateJsonSchemaCommand;
use Sunrise\Http\Router\OpenApi\OpenApi;

/** @var OpenApi $openapi */
$command = new GenerateJsonSchemaCommand($openapi);

php bin/app router:generate-json-schema --help

测试套件

assertResponseBodyMatchesDescription

如果给定的响应体与通过给定 ID 识别的操作描述不匹配，则断言失败。

use PHPUnit\Framework\TestCase;
use Psr\Http\Message\ResponseInterface;
use Sunrise\Http\Router\OpenApi\Test\OpenapiTestKit;

class SomeTest extends TestCase
{
    use OpenapiTestKit;

    public function testResponseBodyMatchesDescription() : void
    {
        // some logic to run a route...

        /** @var ResponseInterface $response */
        $this->assertResponseBodyMatchesDescription('route.name', $response);
    }
}

简单路由描述

class SomeController
{

    /**
     * @OpenApi\Operation(
     *   requestBody=@OpenApi\RequestBody(
     *     content={
     *       "application/json": @OpenApi\MediaType(
     *         schema=@OpenApi\Schema(
     *           type="object",
     *           properties={
     *             "foo": @OpenApi\Schema(
     *               type="string",
     *             ),
     *           },
     *         ),
     *       ),
     *     },
     *   ),
     *   responses={
     *     200: @OpenApi\Response(
     *       description="Ok",
     *     ),
     *   },
     * )
     */
    public function someAction()
    {
    }
}

在此处查找更多示例： Some App