Awesome
OpenAPI (Swagger) Specification Support for Sunrise Router
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