nijens / openapi-bundle
Helps you create a REST API from your OpenAPI specification.
Installs: 53 197
Dependents: 0
Suggesters: 0
Security: 0
Stars: 15
Watchers: 5
Forks: 4
Open Issues: 5
Type:symfony-bundle
Requires
- php: ^7.4 || ^8.0
- ext-json: *
- justinrainbow/json-schema: ^5.2
- league/uri: ^6.3
- seld/jsonlint: ^1.7
- symfony/config: ^5.4 || ^6.0 || ^7.0
- symfony/dependency-injection: ^5.4 || ^6.0 || ^7.0
- symfony/deprecation-contracts: ^2.5 || ^3.0
- symfony/event-dispatcher: ^5.4 || ^6.0 || ^7.0
- symfony/framework-bundle: ^5.4 || ^6.0 || ^7.0
- symfony/http-foundation: ^5.4 || ^6.0 || ^7.0
- symfony/http-kernel: ^5.4 || ^6.0 || ^7.0
- symfony/property-access: ^5.4 || ^6.0 || ^7.0
- symfony/routing: ^5.4 || ^6.0 || ^7.0
- symfony/serializer: ^5.4 || ^6.0 || ^7.0
- symfony/yaml: ^5.4 || ^6.0 || ^7.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- masterminds/html5: ^2.7
- monolog/monolog: ^1.27 || ^2.6 || ^3.0
- phpunit/phpunit: ^9.6
- symfony/browser-kit: ^5.4 || ^6.0 || ^7.0
- symfony/phpunit-bridge: ^5.4 || ^6.0 || ^7.0
- symfony/process: ^5.4 || ^6.0 || ^7.0
- symfony/security-bundle: ^5.4 || ^6.0 || ^7.0
README
Helps you create a REST API from your OpenAPI specification.
This bundle supports a design-first methodology for creating an API with Symfony by providing the following tools:
- Loading the path items and operations of an OpenAPI specification as routes
- Validation of the request to those routes
- Deserialization of a validated JSON request body into an object
- OpenAPI-based serialization context for the Symfony Serializer
- Exception handling
Installation
Applications that use Symfony Flex
Open a command console, enter your project directory and execute:
composer require nijens/openapi-bundle
Applications that don't use Symfony Flex
Step 1: Download the Bundle
Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:
composer require nijens/openapi-bundle
This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.
Step 2: Enable the Bundle
Then, enable the bundle by adding it to the list of registered bundles
in the src/Kernel.php
file of your project:
<?php // src/Kernel.php // ... class Kernel extends BaseKernel { public function registerBundles(): iterable { return [ // ... new Nijens\OpenapiBundle\NijensOpenapiBundle(), ]; } // ... }
Usage
Before starting with the implementation of the bundle, you should take the time to design your API according to the OpenAPI specification.
The following resources can help you with designing the specification:
Routing
This bundle provides a route loader that loads path items and operations from your OpenAPI document.
You load your OpenAPI document by configuring it in the routing of your application:
# app/config/routes.yml api: prefix: /api resource: ../openapi.yaml # or ../openapi.json type: openapi name_prefix: "api_"
Within the OpenAPI document we will use the x-openapi-bundle
specification extension to add additional configuration
to the operations defined in the document.
Configuring a controller for a route
A Symfony controller for a route is configured by adding the controller
property to the x-openapi-bundle
specification extension within an operation within your OpenAPI document.
paths: /pets/{uuid}: put: x-openapi-bundle: controller: 'Nijens\OpenapiBundle\Controller\PetController::put' requestBody: content: application/json: schema: $ref: '#/components/schemas/Pet' responses: '200': description: 'Returns the stored pet.'
Example of an OpenAPI document in JSON format
{ "paths": { "/pets/{uuid}": { "put": { "x-openapi-bundle": { "controller": "Nijens\\OpenapiBundle\\Controller\\PetController::put" }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }, "responses": { "200": { "description": "Returns the stored pet." } } } } } }
The value of the controller
property is the same as you would normally add to a Symfony route.
Using the operationId of an operation as the name of the Symfony route
Within an OpenAPI document, you can give each operation an
operationId to better identify it.
To use the operationId
as the name for a loaded Symfony route, add the following bundle configuration:
# config/packages/nijens_openapi.yaml nijens_openapi: routing: operation_id_as_route_name: true
Using the operationId
for your routes gives you more control over the API route names and allows you to better use
them with a UrlGenerator
.
Validation of the request
By default, the deprecated validation component is enabled. To enable the improved validation component, add the following YAML configuration.
# config/packages/nijens_openapi.yaml nijens_openapi: exception_handling: enabled: true validation: enabled: true
It is strongly advised to also enable the improved exception handling component, as it will convert the details of the validation exceptions into proper JSON responses.
The validation component comes with validation for the following parts of a request:
- Content-type: Based on the configured content types configured in the
requestBody
property of an operation - Query parameters: Validates the query parameters configured of the operation and path item. Note that this type of validation is experimental as it might be missing validation of certain query parameter types.
- JSON request body: Based on the JSON schema in the
requestBody
property of an operation
Learn more
- Activate query parameter request validation
- Create your custom request validator
- Content-type validation explained (coming soon™)
- JSON request body validation explained (coming soon™)
- Query parameter validation explained (coming soon™)
Deserialize a JSON request body
Adding the deserializationObject
property to the x-openapi-bundle
specification extension of an operation activates
the request body deserialization.
When the request body is successfully validated against the JSON schema within your OpenAPI document, it will deserialize the request body into the configured deserialization object.
The deserialized object is injected into the controller based on:
-
The type hint of the argument in the controller method.
-
The
#[DeserializedObject]
parameter attribute. (supported since PHP 8.0)This method is the recommended way, as it supports argument resolving for both array deserialization and mixed argument types.
-
The
deserializationObjectArgumentName
property that can be added to thex-openapi-bundle
specification extension.
Learn more
OpenAPI-based serialization context for the Symfony Serializer
⚠ Please note: This feature is still experimental. The API might change in a future minor version.
The SerializationContextBuilder
helps you with creating a serialization context for the Symfony Serializer.
It allows you to easily create a JSON response from an object or entity based on your OpenAPI specification.
The following example shows how to use the serialization context builder by leveraging the request attributes added by the routing.
<?php use Nijens\OpenapiBundle\Routing\RouteContext; use Nijens\OpenapiBundle\Serialization\SerializationContextBuilderInterface; use Symfony\Component\HttpFoundation\JsonResponse; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\Serializer\SerializerInterface; class ExampleController { public function __invoke( Request $request, SerializerInterface $serializer, SerializationContextBuilderInterface $serializationContextBuilder ): JsonResponse { $pet = new Pet(); $serializationContext = $serializationContextBuilder->getContextForSchemaObject( 'Pet', $request->attributes->get(RouteContext::REQUEST_ATTRIBUTE)[RouteContext::RESOURCE] ); return JsonResponse::fromJsonString( $serializer->serialize($pet, 'json', $serializationContext) ); } }
Exception handling
By default, the previous exception handling component is enabled. To enable the new exception handling component, add the following YAML configuration.
# config/packages/nijens_openapi.yaml nijens_openapi: exception_handling: enabled: true
The new exception handling component uses the Problem Details JSON Object
format to turn an exception (or Throwable
) into a clear error response.
If you want to implement your own exception handling? Change enabled
to false
. It will disable the
exception handling component of the bundle.
Customizing the Problem Details JSON Object response of an exception
Through the exception handling configuration of the bundle, you can modify the response status code and
problem JSON response body of any Throwable
. See the following example for more information.
# config/packages/nijens_openapi.yaml nijens_openapi: exception_handling: enabled: true exceptions: InvalidArgumentException: # The fully qualified classname of the exception. status_code: 400 # Modify the response status code of # the exception response. type_uri: https://example.com/error # Add a unique type URI to the Problem Details. # This could be a URL to additional documentation # about the error. title: The request was invalid. # Add a clear human-readable title property # to the Problem Details. add_instance_uri: true # Add the current route as instance_uri property # to the Problem Details.
To help you include the Problem Details JSON object in your OpenAPI document, we provide an OpenAPI template with schemas for the specific Problem Details JSON objects this bundle creates.
Credits and acknowledgements
- Author: Niels Nijens
Also, see the list of contributors who participated in this project.
License
The OpenAPI bundle is licensed under the MIT License. Please see the LICENSE file for details.