Fix Open Api Definitions models

Author: wbloszyk

UPGRADE-4.x.md

@@ -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
 ========================

docs/reference/api.rst

@@ -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
 
@@ -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 }

src/Controller/Api/GroupController.php

@@ -137,7 +137,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",
@@ -165,7 +165,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",
@@ -193,7 +193,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",

src/Controller/Api/UserController.php

@@ -141,7 +141,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",
@@ -169,7 +169,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",
@@ -197,7 +197,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",
@@ -265,7 +265,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",
@@ -311,7 +311,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",