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
Open a command console, enter your project directory and execute:
composer require nijens/openapi-bundleOpen 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-bundleThis command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.
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(),
];
}
// ...
}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:
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.
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.
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: trueUsing the operationId for your routes gives you more control over the API route names and allows you to better use
them with a UrlGenerator.
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: trueIt 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
requestBodyproperty 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
requestBodyproperty of an operation
- 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™)
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
deserializationObjectArgumentNameproperty that can be added to thex-openapi-bundlespecification extension.
⚠ 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)
);
}
}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: trueThe 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.
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.
- Author: Niels Nijens
Also, see the list of contributors who participated in this project.
The OpenAPI bundle is licensed under the MIT License. Please see the LICENSE file for details.