OpenAPI (Swagger) Specification Support for Sunrise Router

---

Important to understanding

• OpenAPI Specification

Installation

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

QuickStart

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());

Building OpenAPI Document

// 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();

Building JSON Schemas

Converts an operation part to JSON Schema.

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

PSR-15 Middlewares

RequestValidationMiddleware

Validates a request using a route description.

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

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

Symfony Commands

GenerateOpenapiDocumentCommand

Generates OpenAPI document.

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

Generates an operation part to 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

Test Kit

assertResponseBodyMatchesDescription

The assertion fails if the given response body doesn't match a description of the operation identified by the given 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);
    }
}

Simple Route Description

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()
    {
    }
}

---

Look for more examples here: Some App