|
1 | 1 | # OpenAPI-Symfony-Routing |
2 | | -Loads routes in Symfony based on OpenAPI/Swagger annotations |
| 2 | + |
| 3 | +Loads routes in Symfony based on [OpenAPI/Swagger annotations](https://github.com/zircote/swagger-php). |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | + $ composer require tobion/openapi-symfony-routing |
| 10 | + |
| 11 | +## Basic Usage |
| 12 | + |
| 13 | +This library allows to (re-)use your OpenAPI documentation to configure the routing of your Symfony-based API. |
| 14 | +All the relevant routing information like the HTTP method, path and parameters are already part of the OpenAPI spec. |
| 15 | +This way you do not have to duplicate any routing information in Symfony. Consider having the controllers annotated with |
| 16 | +[zircote/swagger-php](https://github.com/zircote/swagger-php) like the following example: |
| 17 | + |
| 18 | +```php |
| 19 | +use Swagger\Annotations as SWG; |
| 20 | + |
| 21 | +/** |
| 22 | + * @SWG\Swagger( |
| 23 | + * @SWG\Info(title="My API", version="1.0") |
| 24 | + * ) |
| 25 | + */ |
| 26 | +class MyController |
| 27 | +{ |
| 28 | + /** |
| 29 | + * @SWG\Get( |
| 30 | + * path="/foobar", |
| 31 | + * @SWG\Response(response="200", description="Success") |
| 32 | + * ) |
| 33 | + */ |
| 34 | + public function __invoke() |
| 35 | + { |
| 36 | + } |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +This library provides an `OpenApiRouteLoader` that you need to define as service and configure where to look for annotations like so: |
| 41 | + |
| 42 | +```yaml |
| 43 | +# config/services.yaml |
| 44 | +services: |
| 45 | + _defaults: |
| 46 | + autoconfigure: true |
| 47 | + |
| 48 | + Tobion\OpenApiSymfonyRouting\OpenApiRouteLoader: |
| 49 | + # Looks for OpenAPI/Swagger annotations in the symfony flex default "src" directory |
| 50 | + factory: [Tobion\OpenApiSymfonyRouting\OpenApiRouteLoader, fromSrcDirectory] |
| 51 | +``` |
| 52 | +
|
| 53 | +Then you need to tell Symfony to load routes using it: |
| 54 | +
|
| 55 | +```yaml |
| 56 | +# config/routes.yaml |
| 57 | +openapi_routes: |
| 58 | + resource: Tobion\OpenApiSymfonyRouting\OpenApiRouteLoader |
| 59 | + type: service |
| 60 | +``` |
| 61 | +
|
| 62 | +## Advanced Features |
| 63 | +
|
| 64 | +### Scanning annotations in different directories |
| 65 | +
|
| 66 | +```yaml |
| 67 | +services: |
| 68 | + Tobion\OpenApiSymfonyRouting\OpenApiRouteLoader: |
| 69 | + factory: [Tobion\OpenApiSymfonyRouting\OpenApiRouteLoader, fromDirectories] |
| 70 | + arguments: |
| 71 | + - '%kernel.project_dir%/src' |
| 72 | + - '%kernel.project_dir%/vendor/acme/my-bundle/src' |
| 73 | +``` |
| 74 | +
|
| 75 | +### Naming routes |
| 76 | +
|
| 77 | +By default routes are auto-named based on the controller class and method. If you want to give routes |
| 78 | +an explicit name, you can do so using the OpenAPI `operationId` property: |
| 79 | + |
| 80 | +```php |
| 81 | +use Swagger\Annotations as SWG; |
| 82 | +
|
| 83 | +class MyController |
| 84 | +{ |
| 85 | + /** |
| 86 | + * @SWG\Get( |
| 87 | + * path="/foobar", |
| 88 | + * operationId="my-name", |
| 89 | + * @SWG\Response(response="200", description="Success") |
| 90 | + * ) |
| 91 | + */ |
| 92 | + public function __invoke() |
| 93 | + { |
| 94 | + } |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +### Add format suffix automatically |
| 99 | + |
| 100 | +If your API supports different formats it is often common to optionally allow specifying the requested format as a suffix |
| 101 | +to the endpoint instead of having to always change headers for content negotiation. |
| 102 | +The routing loader allows to add a `.{_format}` placeholder automatically to the routes. This is disabled by default |
| 103 | +and can be enabled using a `format-suffix` OpenAPI vendor extension: |
| 104 | + |
| 105 | +```php |
| 106 | +use Swagger\Annotations as SWG; |
| 107 | +
|
| 108 | +class MyController |
| 109 | +{ |
| 110 | + /** |
| 111 | + * @SWG\Get( |
| 112 | + * path="/foobar", |
| 113 | + * x={"format-suffix": { |
| 114 | + * "enabled": true, |
| 115 | + * "pattern": "json|xml" |
| 116 | + * }}, |
| 117 | + * @SWG\Response(response="200", description="Success") |
| 118 | + * ) |
| 119 | + */ |
| 120 | + public function __invoke() |
| 121 | + { |
| 122 | + } |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +The above example will create a route `/foobar.{_format}` where the format is optional and can be json or xml. |
| 127 | +You can also enable the format-suffix globally by configuring it on the root Swagger annotation and disable it for |
| 128 | +certain routes again, see [test fixtures](./tests/Fixtures/FormatSuffix/Controller.php). |
| 129 | + |
| 130 | +## Contributing |
| 131 | + |
| 132 | +To run tests: |
| 133 | + |
| 134 | + $ composer install |
| 135 | + $ vendor/bin/simple-phpunit |
0 commit comments