nijens/openapi-bundle

Helps you create a REST API from your OpenAPI specification.

2.1.0 2024-05-15 14:57 UTC

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

MIT

• Niels Nijens

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:

• OpenAPI specification version 3
• Swagger specification editor

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:

1. The type hint of the argument in the controller method.

2. 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.

3. The deserializationObjectArgumentName property that can be added to the x-openapi-bundle specification extension.

Learn more

• How to use a single controller with the Symfony Messenger component

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.