sunrise / http-router-openapi
Sunrise // OpenApi (Swagger) Specification support for Sunrise Router
Installs: 2 235
Dependents: 1
Suggesters: 0
Security: 0
Stars: 4
Watchers: 2
Forks: 1
Open Issues: 14
Requires
- php: ^7.1|^8.0
- doctrine/annotations: ^1.6
Requires (Dev)
- justinrainbow/json-schema: 5.2.10
- phpunit/phpunit: 7.5.20|9.5.0
- sunrise/coding-standard: 1.0.0
- sunrise/http-factory: 1.1.0
- sunrise/http-router: ^2.11
- symfony/console: ^4.4
- dev-master
- v2.2.0
- v2.1.0
- v2.0.0
- v1.10.0
- v1.9.0
- v1.8.0
- v1.7.0
- v1.6.0
- v1.5.1
- v1.5.0
- v1.4.1
- v1.4.0
- v1.3.0
- v1.2.0
- v1.1.1
- v1.1.0
- v1.0.2
- v1.0.1
- v1.0.0
- dev-renovate/phpunit-phpunit-11.x
- dev-renovate/justinrainbow-json-schema-6.x
- dev-renovate/phpunit-phpunit-9.x
- dev-renovate/justinrainbow-json-schema-5.x
- dev-renovate/major-symfony
- dev-renovate/sunrise-http-factory-2.x
- dev-renovate/doctrine-annotations-2.x
- dev-renovate/circleci-php-8.x
- dev-renovate/circleci-php-7.x
- dev-renovate/sunrise-http-factory-1.x
- dev-release/v2.2.0
- dev-release/v2.1.0
- dev-release/v2.0.0
- dev-release/v1.10.0
- dev-release/v1.9.0
- dev-release/v1.8.0
This package is auto-updated.
Last update: 2024-09-04 14:08:10 UTC
README
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