Skip to content

OpenAPI (Swagger) Specification Support for Sunrise Router (and not only)

License

Notifications You must be signed in to change notification settings

sunrise-php/http-router-openapi

Repository files navigation

OpenAPI (Swagger) Specification Support for Sunrise Router

Build Status Code Coverage Scrutinizer Code Quality Total Downloads Latest Stable Version License


Important to understanding

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