Skip to content

Commit 7e39d65

Browse files
TobionTobion
committed
documentation
1 parent 8c6aa25 commit 7e39d65

File tree

10 files changed

+158
-97
lines changed

10 files changed

+158
-97
lines changed

‎README.md

Lines changed: 134 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,135 @@
11
# 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+
![CI](https://github.com/Tobion/OpenAPI-Symfony-Routing/workflows/CI/badge.svg)
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

‎tests/Fixtures/Basic/Controller.php

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,15 @@
88

99
/**
1010
* @SWG\Swagger(
11-
* @SWG\Info(
12-
* title="My API",
13-
* version="1.0"
14-
* )
11+
* @SWG\Info(title="My API", version="1.0")
1512
* )
1613
*/
1714
class Controller
1815
{
1916
/**
2017
* @SWG\Get(
2118
* path="/foobar",
22-
* @SWG\Response(
23-
* response="200",
24-
* description="Success"
25-
* )
19+
* @SWG\Response(response="200", description="Success")
2620
* )
2721
*/
2822
public function __invoke(): void

‎tests/Fixtures/FormatSuffix/Controller.php

Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,7 @@
88

99
/**
1010
* @SWG\Swagger(
11-
* @SWG\Info(
12-
* title="My API",
13-
* version="1.0"
14-
* ),
11+
* @SWG\Info(title="My API", version="1.0"),
1512
* x={"format-suffix": {
1613
* "enabled": true
1714
* }}
@@ -22,10 +19,7 @@ class Controller
2219
/**
2320
* @SWG\Get(
2421
* path="/a",
25-
* @SWG\Response(
26-
* response="200",
27-
* description="Success"
28-
* )
22+
* @SWG\Response(response="200", description="Success")
2923
* )
3024
*/
3125
public function inheritEnabledFormatSuffix(): void
@@ -38,10 +32,7 @@ public function inheritEnabledFormatSuffix(): void
3832
* x={"format-suffix": {
3933
* "pattern": "json|xml"
4034
* }},
41-
* @SWG\Response(
42-
* response="200",
43-
* description="Success"
44-
* )
35+
* @SWG\Response(response="200", description="Success")
4536
* )
4637
*/
4738
public function defineFormatPattern(): void
@@ -52,10 +43,7 @@ public function defineFormatPattern(): void
5243
* @SWG\Get(
5344
* path="/c",
5445
* x={"format-suffix": false},
55-
* @SWG\Response(
56-
* response="200",
57-
* description="Success"
58-
* )
46+
* @SWG\Response(response="200", description="Success")
5947
* )
6048
*/
6149
public function disableFormatSuffix(): void

‎tests/Fixtures/OperationId/Controller.php

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,7 @@
88

99
/**
1010
* @SWG\Swagger(
11-
* @SWG\Info(
12-
* title="My API",
13-
* version="1.0"
14-
* )
11+
* @SWG\Info(title="My API", version="1.0")
1512
* )
1613
*/
1714
class Controller
@@ -20,10 +17,7 @@ class Controller
2017
* @SWG\Get(
2118
* path="/foobar",
2219
* operationId="my-name",
23-
* @SWG\Response(
24-
* response="200",
25-
* description="Success"
26-
* )
20+
* @SWG\Response(response="200", description="Success")
2721
* )
2822
*/
2923
public function __invoke(): void

‎tests/Fixtures/PathParameterPattern/Controller.php

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,7 @@
88

99
/**
1010
* @SWG\Swagger(
11-
* @SWG\Info(
12-
* title="My API",
13-
* version="1.0"
14-
* )
11+
* @SWG\Info(title="My API", version="1.0")
1512
* )
1613
*/
1714
class Controller
@@ -25,10 +22,7 @@ class Controller
2522
* type="string",
2623
* required=true
2724
* ),
28-
* @SWG\Response(
29-
* response="200",
30-
* description="Success"
31-
* )
25+
* @SWG\Response(response="200", description="Success")
3226
* )
3327
*/
3428
public function noPattern(): void
@@ -45,10 +39,7 @@ public function noPattern(): void
4539
* required=true,
4640
* pattern="^[a-zA-Z0-9]+$"
4741
* ),
48-
* @SWG\Response(
49-
* response="200",
50-
* description="Success"
51-
* )
42+
* @SWG\Response(response="200", description="Success")
5243
* )
5344
*/
5445
public function withPattern(): void

‎tests/Fixtures/SeveralClasses/BarController.php

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,15 @@
88

99
/**
1010
* @SWG\Swagger(
11-
* @SWG\Info(
12-
* title="My API",
13-
* version="1.0"
14-
* )
11+
* @SWG\Info(title="My API", version="1.0")
1512
* )
1613
*/
1714
class BarController
1815
{
1916
/**
2017
* @SWG\Get(
2118
* path="/bar",
22-
* @SWG\Response(
23-
* response="200",
24-
* description="Success"
25-
* )
19+
* @SWG\Response(response="200", description="Success")
2620
* )
2721
*/
2822
public function __invoke(): void

‎tests/Fixtures/SeveralClasses/FooController.php

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,7 @@ class FooController
1111
/**
1212
* @SWG\Get(
1313
* path="/foo",
14-
* @SWG\Response(
15-
* response="200",
16-
* description="Success"
17-
* )
14+
* @SWG\Response(response="200", description="Success")
1815
* )
1916
*/
2017
public function __invoke(): void

‎tests/Fixtures/SeveralClasses/SubNamespace/SubController.php

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,7 @@ class SubController
1111
/**
1212
* @SWG\Get(
1313
* path="/sub",
14-
* @SWG\Response(
15-
* response="200",
16-
* description="Success"
17-
* )
14+
* @SWG\Response(response="200", description="Success")
1815
* )
1916
*/
2017
public function __invoke(): void

‎tests/Fixtures/SeveralHttpMethods/Controller.php

Lines changed: 5 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,15 @@
88

99
/**
1010
* @SWG\Swagger(
11-
* @SWG\Info(
12-
* title="My API",
13-
* version="1.0"
14-
* )
11+
* @SWG\Info(title="My API", version="1.0")
1512
* )
1613
*/
1714
class Controller
1815
{
1916
/**
2017
* @SWG\Get(
2118
* path="/foobar",
22-
* @SWG\Response(
23-
* response="200",
24-
* description="Success"
25-
* )
19+
* @SWG\Response(response="200", description="Success")
2620
* )
2721
*/
2822
public function get(): void
@@ -32,10 +26,7 @@ public function get(): void
3226
/**
3327
* @SWG\Put(
3428
* path="/foobar",
35-
* @SWG\Response(
36-
* response="200",
37-
* description="Success"
38-
* )
29+
* @SWG\Response(response="200", description="Success")
3930
* )
4031
*/
4132
public function put(): void
@@ -45,10 +36,7 @@ public function put(): void
4536
/**
4637
* @SWG\Post(
4738
* path="/foobar",
48-
* @SWG\Response(
49-
* response="200",
50-
* description="Success"
51-
* )
39+
* @SWG\Response(response="200", description="Success")
5240
* )
5341
*/
5442
public function post(): void
@@ -58,10 +46,7 @@ public function post(): void
5846
/**
5947
* @SWG\Delete(
6048
* path="/foobar",
61-
* @SWG\Response(
62-
* response="200",
63-
* description="Success"
64-
* )
49+
* @SWG\Response(response="200", description="Success")
6550
* )
6651
*/
6752
public function delete(): void

0 commit comments

Comments
 (0)