{"id":15287392,"url":"https://github.com/nijens/openapi-bundle","last_synced_at":"2026-03-08T23:31:24.135Z","repository":{"id":39674330,"uuid":"134330854","full_name":"nijens/openapi-bundle","owner":"nijens","description":"Helps you create a REST API from your OpenAPI specification.","archived":false,"fork":false,"pushed_at":"2026-01-19T15:25:30.000Z","size":808,"stargazers_count":18,"open_issues_count":7,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-01-19T20:40:00.493Z","etag":null,"topics":["openapi","openapi3","php","symfony","symfony-bundle"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nijens.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-05-21T22:16:39.000Z","updated_at":"2026-01-19T15:25:36.000Z","dependencies_parsed_at":"2024-04-09T10:45:04.170Z","dependency_job_id":"a7757c95-6a12-45f9-80c1-71f8b692b7b0","html_url":"https://github.com/nijens/openapi-bundle","commit_stats":{"total_commits":276,"total_committers":7,"mean_commits":39.42857142857143,"dds":0.1557971014492754,"last_synced_commit":"33cfad4785fedc02b524cbdcaff475f2d6d8ac86"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/nijens/openapi-bundle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nijens%2Fopenapi-bundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nijens%2Fopenapi-bundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nijens%2Fopenapi-bundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nijens%2Fopenapi-bundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nijens","download_url":"https://codeload.github.com/nijens/openapi-bundle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nijens%2Fopenapi-bundle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30276909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T20:45:49.896Z","status":"ssl_error","status_checked_at":"2026-03-08T20:45:49.525Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openapi","openapi3","php","symfony","symfony-bundle"],"created_at":"2024-09-30T15:28:01.448Z","updated_at":"2026-03-08T23:31:24.108Z","avatar_url":"https://github.com/nijens.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAPI bundle\n\n[![Latest version on Packagist][ico-version]][link-version]\n[![Software License][ico-license]][link-license]\n[![Build Status][ico-build]][link-build]\n[![Code Quality][ico-code-quality]][link-code-quality]\n\nHelps you create a REST API from your OpenAPI specification.\n\nThis bundle supports a design-first methodology for creating an API with Symfony by providing the following tools:\n\n* [Loading the path items and operations of an OpenAPI specification as routes](#routing)\n* [Validation of the request to those routes](#validation-of-the-request)\n* [Deserialization of a validated JSON request body into an object](#deserialize-a-json-request-body)\n* [OpenAPI-based serialization context for the Symfony Serializer](#openapi-based-serialization-context-for-the-symfony-serializer)\n* [Exception handling](#exception-handling)\n\n## Installation\n\n### Applications that use Symfony Flex\nOpen a command console, enter your project directory and execute:\n\n```console\ncomposer require nijens/openapi-bundle\n```\n\n### Applications that don't use Symfony Flex\n\n#### Step 1: Download the Bundle\n\nOpen a command console, enter your project directory and execute the\nfollowing command to download the latest stable version of this bundle:\n\n```console\ncomposer require nijens/openapi-bundle\n```\n\nThis command requires you to have Composer installed globally, as explained\nin the [installation chapter](https://getcomposer.org/doc/00-intro.md)\nof the Composer documentation.\n\n#### Step 2: Enable the Bundle\n\nThen, enable the bundle by adding it to the list of registered bundles\nin the `src/Kernel.php` file of your project:\n\n```php\n\u003c?php\n// src/Kernel.php\n\n// ...\nclass Kernel extends BaseKernel\n{\n    public function registerBundles(): iterable\n    {\n        return [\n            // ...\n            new Nijens\\OpenapiBundle\\NijensOpenapiBundle(),\n        ];\n    }\n\n    // ...\n}\n```\n\n## Usage\nBefore starting with the implementation of the bundle, you should take the time to design your API according\nto the OpenAPI specification.\n\nThe following resources can help you with designing the specification:\n* [OpenAPI specification version 3](https://swagger.io/specification)\n* [Swagger specification editor](https://editor.swagger.io)\n\n### Routing\nThis bundle provides a route loader that loads [path items](https://swagger.io/specification/#pathItemObject)\nand [operations](https://swagger.io/specification/#operationObject) from your OpenAPI document.\n\nYou load your OpenAPI document by configuring it in the routing of your application:\n\n```yaml\n# app/config/routes.yml\n\napi:\n    prefix: /api\n    resource: ../openapi.yaml # or ../openapi.json\n    type: openapi\n    name_prefix: \"api_\"\n```\n\nWithin the OpenAPI document we will use the `x-openapi-bundle` specification extension to add additional configuration\nto the operations defined in the document.\n\n#### Configuring a controller for a route\nA Symfony controller for a route is configured by adding the `controller` property to the `x-openapi-bundle`\nspecification extension within an operation within your OpenAPI document.\n\n```yaml\npaths:\n  /pets/{uuid}:\n    put:\n      x-openapi-bundle:\n        controller: 'Nijens\\OpenapiBundle\\Controller\\PetController::put'\n      requestBody:\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/Pet'\n      responses:\n        '200':\n          description: 'Returns the stored pet.'\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eExample of an OpenAPI document in JSON format\u003c/summary\u003e\n\n```json\n{\n  \"paths\": {\n    \"/pets/{uuid}\": {\n      \"put\": {\n        \"x-openapi-bundle\": {\n          \"controller\": \"Nijens\\\\OpenapiBundle\\\\Controller\\\\PetController::put\"\n        },\n        \"requestBody\": {\n          \"content\": {\n            \"application/json\": {\n              \"schema\": {\n                \"$ref\": \"#/components/schemas/Pet\"\n              }\n            }\n          }\n        },\n        \"responses\": {\n          \"200\": {\n            \"description\": \"Returns the stored pet.\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\nThe value of the `controller` property is the same as you would normally add to a [Symfony route](https://symfony.com/doc/current/routing.html#creating-routes).\n\n#### Using the operationId of an operation as the name of the Symfony route\nWithin an OpenAPI document, you can give each operation an\n[operationId](https://spec.openapis.org/oas/latest.html#fixed-fields-7) to better identify it.\nTo use the `operationId` as the name for a loaded Symfony route, add the following bundle configuration:\n\n```yaml\n# config/packages/nijens_openapi.yaml\nnijens_openapi:\n    routing:\n        operation_id_as_route_name: true\n```\n\nUsing the `operationId` for your routes gives you more control over the API route names and allows you to better use\nthem with a `UrlGenerator`.\n\n### Validation of the request\nBy default, the [deprecated validation component](docs/validation/deprecated-validation-component.md) is enabled.\nTo enable the improved validation component, add the following YAML configuration.\n\n```yaml\n# config/packages/nijens_openapi.yaml\nnijens_openapi:\n    exception_handling:\n        enabled: true\n\n    validation:\n        enabled: true\n```\n\nIt is strongly advised to also enable the improved exception handling component, as it will convert the details of\nthe validation exceptions into proper JSON responses.\n\nThe validation component comes with validation for the following parts of a request:\n\n* **Content-type**: Based on the configured content types configured in the `requestBody` property of an operation\n* **Query parameters**: Validates the query parameters configured of the operation and path item.\n  *Note that this type of validation is experimental as it might be missing validation of certain query parameter types.*\n* **JSON request body**: Based on the JSON schema in the `requestBody` property of an operation\n\n#### Learn more\n\n* [Activate query parameter request validation](docs/validation/activate-query-parameter-request-validation.md)\n* [Create your custom request validator](docs/validation/create-your-custom-request-validator.md)\n* Content-type validation explained (coming soon™)\n* JSON request body validation explained (coming soon™)\n* Query parameter validation explained (coming soon™)\n\n### Deserialize a JSON request body\n\nAdding the `deserializationObject` property to the `x-openapi-bundle` specification extension of an operation activates\nthe request body deserialization.\n\nWhen the request body is successfully validated against the JSON schema within your OpenAPI document,\nit will deserialize the request body into the configured deserialization object.\n\nThe deserialized object is injected into the controller based on:\n\n1. The type hint of the argument in the controller method.\n\n2. The `#[DeserializedObject]` parameter attribute. (supported since PHP 8.0)\n\n   This method is the recommended way, as it supports argument resolving for both array deserialization\n   and mixed argument types.\n\n3. The `deserializationObjectArgumentName` property that can be added to the `x-openapi-bundle`\n   specification extension.\n\n#### Learn more\n\n* [How to use a single controller with the Symfony Messenger component](docs/deserialization/how-to-use-a-single-controller-with-the-symfony-messenger-component.md)\n\n### OpenAPI-based serialization context for the Symfony Serializer\n⚠ _**Please note:** This feature is still experimental. The API might change in a future minor version._\n\nThe `SerializationContextBuilder` helps you with creating a serialization context for the Symfony Serializer.\nIt allows you to easily create a JSON response from an object or entity based on your OpenAPI specification.\n\nThe following example shows how to use the serialization context builder by leveraging the request attributes added\nby the routing.\n\n```php\n\u003c?php\n\nuse Nijens\\OpenapiBundle\\Routing\\RouteContext;\nuse Nijens\\OpenapiBundle\\Serialization\\SerializationContextBuilderInterface;\nuse Symfony\\Component\\HttpFoundation\\JsonResponse;\nuse Symfony\\Component\\HttpFoundation\\Request;\nuse Symfony\\Component\\Serializer\\SerializerInterface;\n\nclass ExampleController\n{\n    public function __invoke(\n        Request $request,\n        SerializerInterface $serializer,\n        SerializationContextBuilderInterface $serializationContextBuilder\n    ): JsonResponse {\n        $pet = new Pet();\n\n        $serializationContext = $serializationContextBuilder-\u003egetContextForSchemaObject(\n            'Pet',\n            $request-\u003eattributes-\u003eget(RouteContext::REQUEST_ATTRIBUTE)[RouteContext::RESOURCE]\n        );\n\n        return JsonResponse::fromJsonString(\n            $serializer-\u003eserialize($pet, 'json', $serializationContext)\n        );\n    }\n}\n```\n\n### Exception handling\nBy default, the [previous exception handling component](docs/previous-exception-handling.md) is enabled.\nTo enable the new exception handling component, add the following YAML configuration.\n\n```yaml\n# config/packages/nijens_openapi.yaml\nnijens_openapi:\n    exception_handling:\n        enabled: true\n```\n\nThe new exception handling component uses the [Problem Details JSON Object](https://datatracker.ietf.org/doc/html/rfc7807#section-3)\nformat to turn an exception (or `Throwable`) into a clear error response.\n\nIf you want to implement your own exception handling? Change `enabled` to `false`. It will disable the\nexception handling component of the bundle.\n\n#### Customizing the Problem Details JSON Object response of an exception\nThrough the exception handling configuration of the bundle, you can modify the response status code and\nproblem JSON response body of any `Throwable`. See the following example for more information.\n\n```yaml\n# config/packages/nijens_openapi.yaml\nnijens_openapi:\n    exception_handling:\n        enabled: true\n        exceptions:\n            InvalidArgumentException:               # The fully qualified classname of the exception.\n                status_code: 400                    # Modify the response status code of\n                                                    # the exception response.\n\n                type_uri: https://example.com/error # Add a unique type URI to the Problem Details.\n                                                    # This could be a URL to additional documentation\n                                                    # about the error.\n\n                title: The request was invalid.     # Add a clear human-readable title property\n                                                    # to the Problem Details.\n\n                add_instance_uri: true              # Add the current route as instance_uri property\n                                                    # to the Problem Details.\n```\n\nTo help you include the Problem Details JSON object in your OpenAPI document, we provide an\n[OpenAPI template](src/Resources/specifications/openapi_problemdetails.yaml) with schemas\nfor the specific Problem Details JSON objects this bundle creates.\n\n## Credits and acknowledgements\n\n* Author: [Niels Nijens][link-author]\n\nAlso, see the list of [contributors][link-contributors] who participated in this project.\n\n## License\nThe OpenAPI bundle is licensed under the MIT License. Please see the [LICENSE file][link-license] for details.\n\n[ico-version]: https://img.shields.io/packagist/v/nijens/openapi-bundle.svg\n[ico-pre-release-version]: https://img.shields.io/packagist/vpre/nijens/openapi-bundle.svg\n[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg\n[ico-build]: https://github.com/nijens/openapi-bundle/actions/workflows/continuous-integration.yaml/badge.svg\n[ico-code-quality]: https://scrutinizer-ci.com/g/nijens/openapi-bundle/badges/quality-score.png?b=main\n\n[link-version]: https://packagist.org/packages/nijens/openapi-bundle\n[link-license]: LICENSE\n[link-build]: https://github.com/nijens/openapi-bundle/actions/workflows/continuous-integration.yaml\n[link-coverage]: https://coveralls.io/r/nijens/openapi-bundle?branch=master\n[link-code-quality]: https://scrutinizer-ci.com/g/nijens/openapi-bundle/?branch=master\n[link-author]: https://github.com/niels-nijens\n[link-contributors]: https://github.com/nijens/openapi-bundle/contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnijens%2Fopenapi-bundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnijens%2Fopenapi-bundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnijens%2Fopenapi-bundle/lists"}