Download the PHP package onmoon/openapi-server-bundle without Composer
On this page you can find all versions of the php package onmoon/openapi-server-bundle. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package openapi-server-bundle
Symfony OpenApi Server Bundle
About
This bundle can generate most of the usual boilerplate code you write when implementing an API. The code is generated from OpenAPI specifications.
The following concerns are handled by the bundle automatically:
- Route generation and routing
- Validation of incoming requests against the specification
- Strictly-typed request and response objects and API call handlers interfaces
- Calling your code containing the API call handling logic passing the request object
- Serializing of the returned response object
All you have to do is to implement the API call handler interfaces and return the provided response object.
Installation
The preferred way to install this extension is through composer.
Run
Then add the bundle class to your config/bundles.php
:
Usage
You can configure the bundle by adding the following parameters to your /config/packages/open_api_server.yaml
Add your OpenApi specifications to the application routes configuration file using standard resource
keyword
with open_api
type:
Requirements for your OpenAPI schemas
For the bundle to work properly with your specifications, they should be written in OpenAPI 3.0 format and each
operation must have an unique operationId
.
Currently, there are also the following limitations:
number
withoutformat
is treated as float- Only scalar types are allowed in path and query parameters
- Partial match pattern are ignored in path parameter patterns when selecting route, only
^...$
patterns are used - If pattern is specified in path parameter then type- and format-generated patterns are ignored
- Only one media-type can be used for request and response body schemas. See: https://swagger.io/docs/specification/media-types/
Generating the API Server code
There are two console commands that work with the generated API server code:
- Generate the server code:
php bin/console open-api:generate
- Delete the server code:
php bin/console open-api:delete
Most of the time you should use the generate
command.
It will clear the bundle cache, delete the old generated server code if it exists and generate the new code.
Be careful with the generate and delete commands, they will delete the entire contents of the directory you have specified
in root_path
in the /config/packages/open_api_server.yaml
file. That directory should contain no files except
the code generated by this bundle, as it will be deleted every time you generate the API server code.
For each operation described in the specification, a API call handler interface will be generated that you should implement to handle the API calls.
Implementing the API call handlers interfaces
Given the following generated API handler interface:
Your API call handler could look like this:
Additionally, your API call handler can implement the following interfaces:
\OnMoon\OpenApiServerBundle\Interfaces\SetClientIp
- if it needs the client IP address\OnMoon\OpenApiServerBundle\Interfaces\SetRequest
- if it needs the Symfony request object\OnMoon\OpenApiServerBundle\Interfaces\GetResponseCode
- if it needs to specify custom HTTP response codes
Using DTO mapper
If you want to use Doctrine entities or other business logic classes as sources for API response, you can easily copy contents into DTO using DTO mapper.
Install it with
And use like follows
Customizing the API server behavior
During the request handling lyfecycle the API server emits several events that can be used instead of the built-in Symfony Kernel events as the former provide more context. Theese events allow hooking into the API server functionality and modify it's behavior.
The following events are available:
-
OnMoon\OpenApiServerBundle\Event\Server\RequestEvent
The RequestEvent event occurs right before the request is validated against the OpenAPI Schema. This event allows you to modify the Operation and Request objects prior to performing the validation and processing the request.
-
OnMoon\OpenApiServerBundle\Event\Server\RequestDtoEvent
The RequestDtoEvent event occurs after the Request contents are deserialized in a Dto object representing the API request and before this object is passed to your RequestHandler implementation. This event allows you to modify the Operation and Request DTO (only via reflection) before it will be passed to your RequestHandler implementation. Note that the ResponseDTO is not created if the API endpoint expects no request body, path or query parameters.
-
OnMoon\OpenApiServerBundle\Event\Server\ResponseDtoEvent
The ResponseDtoEvent event occurs after the request handler class was executed returning a ResponseDto and before this ResponseDto is serialized to a Response. This event allows you to modify the ResponseDto contents before it will be serialized. This can be used as an alternative to modyfing the Response object in a Symfony ResponseEvent, avoiding unnecessary decoding/encoding of the Response body json. Note that the ResponseDTO is not created if the API endpoint has no response body.
-
OnMoon\OpenApiServerBundle\Event\Server\ResponseEvent
The ResponseEvent event occurs right before the response is sent by the API server. This event allows you to modify the Response object before the server will emit it to the client.
Customizing API server code generation
During API server code generation the code generator emits several events that can be used to modify the generated code either by changing parts of the OpenAPI specification objects or by changing the objects representing the various code definitions like classes, properties, methods.
The following events are available:
-
OnMoon\OpenApiServerBundle\Event\CodeGenerator\ClassGraphReadyEvent
The ClassGraphReadyEvent event occurs after all specifications has been parsed and graph of classes to be generated has been constructed.
This event allows you to modify:
- Class names, namespaces and paths,
- Property attributes, getters and setters,
- Base interfaces and classes.
-
OnMoon\OpenApiServerBundle\Event\CodeGenerator\FilesReadyEvent
The FilesReadyEvent event occurs after all class files are generated before they are written to files.
This event allows you to modify generated files content, e.g. change code style.
All versions of openapi-server-bundle with dependencies
ext-json Version *
cebe/php-openapi Version 1.6.99
league/openapi-psr7-validator Version ^0.22.0
lukasoppermann/http-status Version ^4.0
nikic/php-parser Version ^4.19
nyholm/psr7 Version ^1.5
phpdocumentor/reflection-docblock Version ^5.3
sspat/reserved-words Version ^3.0
symfony/cache Version ^6.4|^7.0
symfony/cache-contracts Version ^3.5
symfony/config Version ^6.4|^7.0
symfony/console Version ^6.4|^7.0
symfony/dependency-injection Version ^6.4|^7.0
symfony/event-dispatcher Version ^6.4|^7.0
symfony/http-kernel Version ^6.4|^7.0
symfony/psr-http-message-bridge Version ^6.4|^7.0
symfony/routing Version ^6.4|^7.0
symfony/yaml Version ^6.4|^7.0
thecodingmachine/safe Version ^1.3|^2