Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix Open Api models to be equal with return data #1239

Closed
wants to merge 1 commit into from
Closed

Fix Open Api models to be equal with return data #1239

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 23 additions & 8 deletions UPGRADE-4.x.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,16 +16,31 @@ UPGRADE FROM 4.x to 4.x

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.

### Fix REST API routing paths
### Fix REST API

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).
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:
- Routing paths

sonata_api_user:
prefix: /api/user
resource: "@SonataUserBundle/Resources/config/routing/standard_api.xml"
# or for NelmioApiDocBundle v3
#resource: "@SonataUserBundle/Resources/config/routing/standard_api_nelmio_v3.xml"
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).
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:

sonata_api_user:
prefix: /api/user
resource: "@SonataUserBundle/Resources/config/routing/standard_api.xml"
# or for NelmioApiDocBundle v3
#resource: "@SonataUserBundle/Resources/config/routing/standard_api_nelmio_v3.xml"

- Open Api Definitions

If you want use NelmioApiDocBudle v3 you MUST add extra config for it:

nelmio_api_doc:
models:
names:
- { alias: SonataUserGroup, type: '%sonata.user.admin.group.entity%', groups: [sonata_api_read] }
- { alias: SonataUserUser, type: '%sonata.user.admin.user.entity%', groups: [sonata_api_read] }
# or these alias for ODM
#- { alias: SonataUserGroup, type: '%sonata.user.admin.group.document%', groups: [sonata_api_read] }
#- { alias: SonataUserUser, type: '%sonata.user.admin.user.document%', groups: [sonata_api_read] }

UPGRADE FROM 4.6 to 4.7
========================
Expand Down
35 changes: 35 additions & 0 deletions docs/reference/api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,15 @@ Here's the configuration we used, you may adapt it to your needs:
router: { annotations: true }
request: { converters: true }

nelmio_api_doc:
models:
names:
- { alias: SonataUserGroup, type: '%sonata.user.admin.group.entity%', groups: [sonata_api_read] }
- { alias: SonataUserUser, type: '%sonata.user.admin.user.entity%', groups: [sonata_api_read] }
# or these alias for ODM
#- { alias: SonataUserGroup, type: '%sonata.user.admin.group.document%', groups: [sonata_api_read] }
#- { alias: SonataUserUser, type: '%sonata.user.admin.user.document%', groups: [sonata_api_read] }

twig:
exception_controller: null

Expand All @@ -60,3 +69,29 @@ The taxonomy is as follows:
* ``sonata_api_write`` is the group used for input entities (when used instead of forms)

If you wish to customize the outputted data, feel free to set up your own serialization options by configuring `JMSSerializer` with those groups.

Documentation
-------------

In order to activate the API’s documentation, you’ll also need to add this to your routing:

.. code-block:: yaml

## Requires the Asset component and the Twig bundle
## $ composer require twig asset
app.swagger_ui:
path: /api/doc
methods: GET
defaults: { _controller: nelmio_api_doc.controller.swagger_ui }

Open Api Definition
-------------------

You can generate your Open Api Definitions after add this to your routing:

.. code-block:: yaml

app.swagger:
path: /api/doc.json
methods: GET
defaults: { _controller: nelmio_api_doc.controller.swagger }
16 changes: 11 additions & 5 deletions src/Controller/Api/GroupController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@
use FOS\RestBundle\Request\ParamFetcherInterface;
use FOS\RestBundle\View\View as FOSRestView;
use FOS\UserBundle\Model\GroupInterface;
use Nelmio\ApiDocBundle\Annotation\Model;
use Nelmio\ApiDocBundle\Annotation\Operation;
use Sonata\DatagridBundle\Pager\PagerInterface;
use Sonata\UserBundle\Model\GroupManagerInterface;
Expand Down Expand Up @@ -91,7 +90,14 @@ public function __construct(GroupManagerInterface $groupManager, FormFactoryInte
* @SWG\Response(
* response="200",
* description="Returned when successful",
* @SWG\Schema(ref=@Model(type="Sonata\DatagridBundle\Pager\PagerInterface"))
* @SWG\Schema(
* type="object",
* @SWG\Property(property="page", type="integer"),
* @SWG\Property(property="per_page", type="integer"),
* @SWG\Property(property="last_page", type="integer"),
* @SWG\Property(property="total", type="integer"),
* @SWG\Property(property="entries", type="array", @SWG\Items(ref="#/definitions/SonataUserGroup") ))
* )
* )
* )
*
Expand Down Expand Up @@ -137,7 +143,7 @@ public function getGroupsAction(ParamFetcherInterface $paramFetcher)
* @SWG\Response(
* response="200",
* description="Returned when successful",
* @SWG\Schema(ref=@Model(type="FOS\UserBundle\Model\GroupInterface"))
* @SWG\Schema(ref="#/definitions/SonataUserGroup")
* ),
* @SWG\Response(
* response="404",
Expand Down Expand Up @@ -165,7 +171,7 @@ public function getGroupAction($id)
* @SWG\Response(
* response="200",
* description="Returned when successful",
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\Group"))
* @SWG\Schema(ref="#/definitions/SonataUserGroup")
* ),
* @SWG\Response(
* response="400",
Expand Down Expand Up @@ -193,7 +199,7 @@ public function postGroupAction(Request $request)
* @SWG\Response(
* response="200",
* description="Returned when successful",
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\Group"))
* @SWG\Schema(ref="#/definitions/SonataUserGroup")
* ),
* @SWG\Response(
* response="400",
Expand Down
20 changes: 13 additions & 7 deletions src/Controller/Api/UserController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@
use FOS\RestBundle\Request\ParamFetcherInterface;
use FOS\RestBundle\View\View as FOSRestView;
use FOS\UserBundle\Model\GroupInterface;
use Nelmio\ApiDocBundle\Annotation\Model;
use Nelmio\ApiDocBundle\Annotation\Operation;
use Sonata\DatagridBundle\Pager\PagerInterface;
use Sonata\UserBundle\Model\GroupManagerInterface;
Expand Down Expand Up @@ -95,7 +94,14 @@ public function __construct(UserManagerInterface $userManager, GroupManagerInter
* @SWG\Response(
* response="200",
* description="Returned when successful",
* @SWG\Schema(ref=@Model(type="Sonata\DatagridBundle\Pager\PagerInterface"))
* @SWG\Schema(
* type="object",
* @SWG\Property(property="page", type="integer"),
* @SWG\Property(property="per_page", type="integer"),
* @SWG\Property(property="last_page", type="integer"),
* @SWG\Property(property="total", type="integer"),
* @SWG\Property(property="entries", type="array", @SWG\Items(ref="#/definitions/SonataUserUser") ))
* )
* )
* )
*
Expand Down Expand Up @@ -141,7 +147,7 @@ public function getUsersAction(ParamFetcherInterface $paramFetcher)
* @SWG\Response(
* response="200",
* description="Returned when successful",
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\UserInterface"))
* @SWG\Schema(ref="#/definitions/SonataUserUser")
* ),
* @SWG\Response(
* response="404",
Expand Down Expand Up @@ -169,7 +175,7 @@ public function getUserAction($id)
* @SWG\Response(
* response="200",
* description="Returned when successful",
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\Group"))
* @SWG\Schema(ref="#/definitions/SonataUserGroup")
* ),
* @SWG\Response(
* response="400",
Expand Down Expand Up @@ -197,7 +203,7 @@ public function postUserAction(Request $request)
* @SWG\Response(
* response="200",
* description="Returned when successful",
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\User"))
* @SWG\Schema(ref="#/definitions/SonataUserUser")
* ),
* @SWG\Response(
* response="400",
Expand Down Expand Up @@ -265,7 +271,7 @@ public function deleteUserAction($id)
* @SWG\Response(
* response="200",
* description="Returned when successful",
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\User"))
* @SWG\Schema(ref="#/definitions/SonataUserUser")
* ),
* @SWG\Response(
* response="400",
Expand Down Expand Up @@ -311,7 +317,7 @@ public function postUserGroupAction($userId, $groupId)
* @SWG\Response(
* response="200",
* description="Returned when successful",
* @SWG\Schema(ref=@Model(type="Sonata\UserBundle\Model\User"))
* @SWG\Schema(ref="#/definitions/SonataUserUser")
* ),
* @SWG\Response(
* response="400",
Expand Down