{"id":16770904,"url":"https://github.com/tobion/openapi-symfony-routing","last_synced_at":"2025-03-17T02:31:30.831Z","repository":{"id":41849964,"uuid":"267607067","full_name":"Tobion/OpenAPI-Symfony-Routing","owner":"Tobion","description":"Loads routes in Symfony based on OpenAPI/Swagger annotations","archived":false,"fork":false,"pushed_at":"2022-05-02T19:33:35.000Z","size":28,"stargazers_count":41,"open_issues_count":4,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-27T16:47:22.662Z","etag":null,"topics":["openapi","routing","symfony"],"latest_commit_sha":null,"homepage":null,"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/Tobion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-28T14:08:21.000Z","updated_at":"2024-03-28T23:37:24.000Z","dependencies_parsed_at":"2022-08-11T19:20:48.881Z","dependency_job_id":null,"html_url":"https://github.com/Tobion/OpenAPI-Symfony-Routing","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tobion%2FOpenAPI-Symfony-Routing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tobion%2FOpenAPI-Symfony-Routing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tobion%2FOpenAPI-Symfony-Routing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tobion%2FOpenAPI-Symfony-Routing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tobion","download_url":"https://codeload.github.com/Tobion/OpenAPI-Symfony-Routing/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243841125,"owners_count":20356440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","routing","symfony"],"created_at":"2024-10-13T06:25:57.612Z","updated_at":"2025-03-17T02:31:30.384Z","avatar_url":"https://github.com/Tobion.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAPI-Symfony-Routing\n\nLoads routes in Symfony based on [OpenAPI/Swagger annotations](https://github.com/zircote/swagger-php).\n\n[![CI](https://github.com/Tobion/OpenAPI-Symfony-Routing/workflows/CI/badge.svg)](https://github.com/Tobion/OpenAPI-Symfony-Routing/actions)\n\n## Installation\n\n    $ composer require tobion/openapi-symfony-routing\n\nVersion \u003e= 1.2 requires zircote/swagger-php 3.x which is compatible with the OpenAPI Specification version 3.\nVersion \u003c 1.2 requires zircote/swagger-php 2.x which works with the OpenAPI Specification version 2 (fka Swagger).\nSo tobion/openapi-symfony-routing can be used with both OpenAPI v2 and v3 and composer will select the compatible one for your dependencies.\nRoute loading stays the same between those versions. You just need to update the annotations when migrating from OpenAPI v2 to v3.\n\n## Basic Usage\n\nThis library allows to (re-)use your OpenAPI documentation to configure the routing of your Symfony-based API.\nAll the relevant routing information like the HTTP method, path and parameters are already part of the OpenAPI spec.\nThis way you do not have to duplicate any routing information in Symfony. Consider having the controllers annotated with\n[zircote/swagger-php](https://github.com/zircote/swagger-php) like the following example:\n\n```php\nuse OpenApi\\Annotations as OA;\n\n/**\n * @OA\\OpenApi(\n *     @OA\\Info(title=\"My API\", version=\"1.0\")\n * )\n */\nclass MyController\n{\n    /**\n     * @OA\\Get(\n     *     path=\"/foobar\",\n     *     @OA\\Response(response=\"200\", description=\"Success\")\n     * )\n     */\n    public function __invoke()\n    {\n    }\n}\n```\n\nThis library provides an `OpenApiRouteLoader` that you need to define as service and configure where to look for annotations like so:\n\n```yaml\n# config/services.yaml\nservices:\n    Tobion\\OpenApiSymfonyRouting\\OpenApiRouteLoader:\n        autoconfigure: true\n        # Looks for OpenAPI/Swagger annotations in the symfony flex default \"src\" directory\n        factory: [Tobion\\OpenApiSymfonyRouting\\OpenApiRouteLoader, fromSrcDirectory]\n```\n\nThen you need to tell Symfony to load routes using it:\n\n```yaml\n# config/routes.yaml\nopenapi_routes:\n    resource: Tobion\\OpenApiSymfonyRouting\\OpenApiRouteLoader\n    type: service\n```\n\n## Advanced Features\n\n### Scanning annotations in different directories\n\n```yaml\nservices:\n    Tobion\\OpenApiSymfonyRouting\\OpenApiRouteLoader:\n        autoconfigure: true\n        factory: [Tobion\\OpenApiSymfonyRouting\\OpenApiRouteLoader, fromDirectories]\n        arguments:\n            - '%kernel.project_dir%/src'\n            - '%kernel.project_dir%/vendor/acme/my-bundle/src'\n```\n\n### Naming routes\n\nBy default routes are auto-named based on the controller class and method. If you want to give routes\nan explicit name, you can do so using the OpenAPI `operationId` property:\n\n```php\nuse OpenApi\\Annotations as OA;\n\nclass MyController\n{\n    /**\n     * @OA\\Get(\n     *     path=\"/foobar\",\n     *     operationId=\"my-name\",\n     *     @OA\\Response(response=\"200\", description=\"Success\")\n     * )\n     */\n    public function __invoke()\n    {\n    }\n}\n```\n\n### Add format suffix automatically\n\nIf your API supports different formats it is often common to optionally allow specifying the requested format as a suffix\nto the endpoint instead of having to always change headers for content negotiation.\nThe routing loader allows to add a `.{_format}` placeholder automatically to the routes. This is disabled by default\nand can be enabled using a `format-suffix` OpenAPI vendor extension:\n\n```php\nuse OpenApi\\Annotations as OA;\n\nclass MyController\n{\n    /**\n     * @OA\\Get(\n     *     path=\"/foobar\",\n     *     x={\"format-suffix\": {\n     *         \"enabled\": true,\n     *         \"pattern\": \"json|xml\"\n     *     }},\n     *     @OA\\Response(response=\"200\", description=\"Success\")\n     * )\n     */\n    public function __invoke()\n    {\n    }\n}\n```\n\nThe above example will create a route `/foobar.{_format}` where the format is optional and can be json or xml.\nYou can also enable the format-suffix globally by configuring it on the root OpenApi annotation and disable it for\ncertain routes again, see [test fixtures](./tests/Fixtures/FormatSuffix/Controller.php).\n\n### Order routes with priority\n\nSince Symfony 5.1, the order of routes defined using annotations can be [influenced using a priority](https://symfony.com/doc/current/routing.html#priority-parameter).\nThis can be used to make sure templated routes do not match before concrete routes without parameters for the same URL.\nThe priority can also be set on OpenAPI annotations using a `priority` vendor extension:\n\n```php\nuse OpenApi\\Annotations as OA;\n\nclass MyController\n{\n    /**\n     * @OA\\Get(\n     *     path=\"/foobar\",\n     *     x={\"priority\": 10},\n     *     @OA\\Response(response=\"200\", description=\"Success\")\n     * )\n     */\n    public function __invoke()\n    {\n    }\n}\n```\n\n## Contributing\n\nTo run tests:\n\n    $ composer install\n    $ vendor/bin/simple-phpunit\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobion%2Fopenapi-symfony-routing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobion%2Fopenapi-symfony-routing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobion%2Fopenapi-symfony-routing/lists"}