Skip to content

Commit 5a8906d

Browse files
wbloszykwbloszyk
committed
Fix Open Api Definitions models
1 parent 05bff41 commit 5a8906d

File tree

4 files changed

+82
-20
lines changed

4 files changed

+82
-20
lines changed

‎UPGRADE-4.x.md

+23-8
Original file line numberDiff line numberDiff line change
@@ -16,16 +16,31 @@ UPGRADE FROM 4.x to 4.x
1616

1717
Controllers for NelmioApiDocBundle v2 were moved under `Sonata\UserBundle\Controller\Api\Legacy\` namespace and controllers for NelmioApiDocBundle v3 were added as replacement. If you extend them, you must ensure they are using the corresponding inheritance.
1818

19-
### Fix REST API routing paths
19+
### Fix REST API
2020

21-
In version 4.6.0 some extra REST API routes were added by mistake, creating new duplicated paths pointing to existing actions (by instance `/groups/{id}.{_format}` was duplicated as `/group/{id}.{_format}`, `/users/{id}.{_format}` was duplicated as `/user/{id}.{_format}`, etc).
22-
You MUST avoid importing these routes in order to keep your API routing clean and consistent with previous versions. To do so, make sure to import some of these routing files, depending on your needs:
21+
- Routing paths
2322

24-
sonata_api_user:
25-
prefix: /api/user
26-
resource: "@SonataUserBundle/Resources/config/routing/standard_api.xml"
27-
# or for NelmioApiDocBundle v3
28-
#resource: "@SonataUserBundle/Resources/config/routing/standard_api_nelmio_v3.xml"
23+
In version 4.6.0 some extra REST API routes were added by mistake, creating new duplicated paths pointing to existing actions (by instance `/groups/{id}.{_format}` was duplicated as `/group/{id}.{_format}`, `/users/{id}.{_format}` was duplicated as `/user/{id}.{_format}`, etc).
24+
You MUST avoid importing these routes in order to keep your API routing clean and consistent with previous versions. To do so, make sure to import some of these routing files, depending on your needs:
25+
26+
sonata_api_user:
27+
prefix: /api/user
28+
resource: "@SonataUserBundle/Resources/config/routing/standard_api.xml"
29+
# or for NelmioApiDocBundle v3
30+
#resource: "@SonataUserBundle/Resources/config/routing/standard_api_nelmio_v3.xml"
31+
32+
- Open Api Definitions
33+
34+
If you want use NelmioApiDocBudle v3 you MUST add extra config for it:
35+
36+
nelmio_api_doc:
37+
models:
38+
names:
39+
- { alias: SonataUserGroup, type: '%sonata.user.admin.group.entity%', groups: [sonata_api_read] }
40+
- { alias: SonataUserUser, type: '%sonata.user.admin.user.entity%', groups: [sonata_api_read] }
41+
# or these alias for ODM
42+
#- { alias: SonataUserGroup, type: '%sonata.user.admin.group.document%', groups: [sonata_api_read] }
43+
#- { alias: SonataUserUser, type: '%sonata.user.admin.user.document%', groups: [sonata_api_read] }
2944

3045
UPGRADE FROM 4.6 to 4.7
3146
========================

‎docs/reference/api.rst

+35
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,15 @@ Here's the configuration we used, you may adapt it to your needs:
3535
router: { annotations: true }
3636
request: { converters: true }
3737
38+
nelmio_api_doc:
39+
models:
40+
names:
41+
- { alias: SonataUserGroup, type: '%sonata.user.admin.group.entity%', groups: [sonata_api_read] }
42+
- { alias: SonataUserUser, type: '%sonata.user.admin.user.entity%', groups: [sonata_api_read] }
43+
# or these alias for ODM
44+
#- { alias: SonataUserGroup, type: '%sonata.user.admin.group.document%', groups: [sonata_api_read] }
45+
#- { alias: SonataUserUser, type: '%sonata.user.admin.user.document%', groups: [sonata_api_read] }
46+
3847
twig:
3948
exception_controller: null
4049
@@ -60,3 +69,29 @@ The taxonomy is as follows:
6069
* ``sonata_api_write`` is the group used for input entities (when used instead of forms)
6170

6271
If you wish to customize the outputted data, feel free to set up your own serialization options by configuring `JMSSerializer` with those groups.
72+
73+
Documentation
74+
-------------
75+
76+
In order to activate the API’s documentation, you’ll also need to add this to your routing:
77+
78+
.. code-block:: yaml
79+
80+
## Requires the Asset component and the Twig bundle
81+
## $ composer require twig asset
82+
app.swagger_ui:
83+
path: /api/doc
84+
methods: GET
85+
defaults: { _controller: nelmio_api_doc.controller.swagger_ui }
86+
87+
Open Api Definition
88+
-------------------
89+
90+
You can generate your Open Api Definitions after add this to your routing:
91+
92+
.. code-block:: yaml
93+
94+
app.swagger:
95+
path: /api/doc.json
96+
methods: GET
97+
defaults: { _controller: nelmio_api_doc.controller.swagger }

‎src/Controller/Api/GroupController.php

+11-5
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@
1919
use FOS\RestBundle\Request\ParamFetcherInterface;
2020
use FOS\RestBundle\View\View as FOSRestView;
2121
use FOS\UserBundle\Model\GroupInterface;
22-
use Nelmio\ApiDocBundle\Annotation\Model;
2322
use Nelmio\ApiDocBundle\Annotation\Operation;
2423
use Sonata\DatagridBundle\Pager\PagerInterface;
2524
use Sonata\UserBundle\Model\GroupManagerInterface;
@@ -91,7 +90,14 @@ public function __construct(GroupManagerInterface $groupManager, FormFactoryInte
9190
* @SWG\Response(
9291
* response="200",
9392
* description="Returned when successful",
94-
* @SWG\Schema(ref=@Model(type="Sonata\DatagridBundle\Pager\PagerInterface"))
93+
* @SWG\Schema(
94+
* type="object",
95+
* @SWG\Property(property="page", type="integer"),
96+
* @SWG\Property(property="per_page", type="integer"),
97+
* @SWG\Property(property="last_page", type="integer"),
98+
* @SWG\Property(property="total", type="integer"),
99+
* @SWG\Property(property="entries", type="array", @SWG\Items(ref="#/definitions/SonataUserGroup") ))
100+
* )
95101
* )
96102
* )
97103
*
@@ -137,7 +143,7 @@ public function getGroupsAction(ParamFetcherInterface $paramFetcher)
137143
* @SWG\Response(
138144
* response="200",
139145
* description="Returned when successful",
140-
* @SWG\Schema(ref=@Model(type="FOS\UserBundle\Model\GroupInterface"))
146+
* @SWG\Schema(ref="#/definitions/SonataUserGroup")
141147
* ),
142148
* @SWG\Response(
143149
* response="404",
@@ -165,7 +171,7 @@ public function getGroupAction($id)
165171
* @SWG\Response(
166172
* response="200",
167173
* description="Returned when successful",
168-
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\Group"))
174+
* @SWG\Schema(ref="#/definitions/SonataUserGroup")
169175
* ),
170176
* @SWG\Response(
171177
* response="400",
@@ -193,7 +199,7 @@ public function postGroupAction(Request $request)
193199
* @SWG\Response(
194200
* response="200",
195201
* description="Returned when successful",
196-
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\Group"))
202+
* @SWG\Schema(ref="#/definitions/SonataUserGroup")
197203
* ),
198204
* @SWG\Response(
199205
* response="400",

‎src/Controller/Api/UserController.php

+13-7
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@
1919
use FOS\RestBundle\Request\ParamFetcherInterface;
2020
use FOS\RestBundle\View\View as FOSRestView;
2121
use FOS\UserBundle\Model\GroupInterface;
22-
use Nelmio\ApiDocBundle\Annotation\Model;
2322
use Nelmio\ApiDocBundle\Annotation\Operation;
2423
use Sonata\DatagridBundle\Pager\PagerInterface;
2524
use Sonata\UserBundle\Model\GroupManagerInterface;
@@ -95,7 +94,14 @@ public function __construct(UserManagerInterface $userManager, GroupManagerInter
9594
* @SWG\Response(
9695
* response="200",
9796
* description="Returned when successful",
98-
* @SWG\Schema(ref=@Model(type="Sonata\DatagridBundle\Pager\PagerInterface"))
97+
* @SWG\Schema(
98+
* type="object",
99+
* @SWG\Property(property="page", type="integer"),
100+
* @SWG\Property(property="per_page", type="integer"),
101+
* @SWG\Property(property="last_page", type="integer"),
102+
* @SWG\Property(property="total", type="integer"),
103+
* @SWG\Property(property="entries", type="array", @SWG\Items(ref="#/definitions/SonataUserUser") ))
104+
* )
99105
* )
100106
* )
101107
*
@@ -141,7 +147,7 @@ public function getUsersAction(ParamFetcherInterface $paramFetcher)
141147
* @SWG\Response(
142148
* response="200",
143149
* description="Returned when successful",
144-
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\UserInterface"))
150+
* @SWG\Schema(ref="#/definitions/SonataUserUser")
145151
* ),
146152
* @SWG\Response(
147153
* response="404",
@@ -169,7 +175,7 @@ public function getUserAction($id)
169175
* @SWG\Response(
170176
* response="200",
171177
* description="Returned when successful",
172-
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\Group"))
178+
* @SWG\Schema(ref="#/definitions/SonataUserGroup")
173179
* ),
174180
* @SWG\Response(
175181
* response="400",
@@ -197,7 +203,7 @@ public function postUserAction(Request $request)
197203
* @SWG\Response(
198204
* response="200",
199205
* description="Returned when successful",
200-
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\User"))
206+
* @SWG\Schema(ref="#/definitions/SonataUserUser")
201207
* ),
202208
* @SWG\Response(
203209
* response="400",
@@ -265,7 +271,7 @@ public function deleteUserAction($id)
265271
* @SWG\Response(
266272
* response="200",
267273
* description="Returned when successful",
268-
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\User"))
274+
* @SWG\Schema(ref="#/definitions/SonataUserUser")
269275
* ),
270276
* @SWG\Response(
271277
* response="400",
@@ -311,7 +317,7 @@ public function postUserGroupAction($userId, $groupId)
311317
* @SWG\Response(
312318
* response="200",
313319
* description="Returned when successful",
314-
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\User"))
320+
* @SWG\Schema(ref="#/definitions/SonataUserUser")
315321
* ),
316322
* @SWG\Response(
317323
* response="400",

0 commit comments

Comments
 (0)