Fixed and enhanced OpenAPI

src/bundle/Resources/api_platform/examples/user/groups/GET/UserGroupRefList.json.example

@@ -0,0 +1,12 @@
+{
+    "UserGroupRefList": {
+        "_media-type": "application/vnd.ibexa.api.UserGroupRefList+json",
+        "_href": "/api/ibexa/v2/user/users/57/groups",
+        "UserGroup": [
+            {
+                "_media-type": "application/vnd.ibexa.api.UserGroup+json",
+                "_href": "/api/ibexa/v2/user/groups/1/5/13"
+            }
+        ]
+    }
+}

src/bundle/Resources/api_platform/examples/user/groups/GET/UserGroupRefList.xml.example

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<UserGroupRefList media-type="application/vnd.ibexa.api.UserGroupRefList+xml" href="/api/ibexa/v2/user/users/115/groups">
+    <UserGroup media-type="application/vnd.ibexa.api.UserGroup+xml" href="/api/ibexa/v2/user/groups/1/5/12">
+        <unassign href="/api/ibexa/v2/user/users/79/groups/12" method="DELETE"/>
+    </UserGroup>
+    <UserGroup media-type="application/vnd.ibexa.api.UserGroup+xml" href="/api/ibexa/v2/user/groups/1/5/13">
+        <unassign href="/api/ibexa/v2/user/users/115/groups/13" method="DELETE"/>
+    </UserGroup>
+</UserGroupRefList>

src/bundle/Resources/api_platform/schemas/user/roles_schemas.yml

@@ -136,7 +136,7 @@ schemas:
                 description: A read-only list of IDs or identifiers for which the limitation should be applied. The value of this property must conform to a hash, which means that it may only consist of array and scalar values, but must not contain objects or resources.
                 type: object
                 required:
-                    - $ref
+                    - ref
                 properties:
                     ref:
                         type: array

src/lib/Server/Controller/JWT.php

@@ -19,6 +19,7 @@
     uriTemplate: '/user/token/jwt',
     extraProperties: [OpenApiFactory::OVERRIDE_OPENAPI_RESPONSES => false],
     openapi: new Model\Operation(
+        operationId: 'ibexa.rest.create_token',
         summary: 'Create JWT token',
         description: 'Creates JWT authentication token.',
         tags: [

src/lib/Server/Controller/Session/SessionCheckController.php

@@ -17,6 +17,7 @@
 #[Get(
     uriTemplate: '/user/sessions/current',
     openapi: new Model\Operation(
+        operationId: 'ibexa.rest.check_session',
         summary: 'Get current session',
         description: 'Get current user session, if any.',
         tags: [
@@ -26,38 +27,29 @@
             new Model\Parameter(
                 name: 'Cookie',
                 in: 'header',
-                required: true,
+                required: false,
                 description: 'Only needed for session\'s checking {sessionName}={sessionID}.',
                 schema: [
                     'type' => 'string',
                 ],
             ),
-            new Model\Parameter(
-                name: 'Accept',
-                in: 'header',
-                required: true,
-                description: 'If set, the session is returned in XML or JSON format.',
-                schema: [
-                    'type' => 'string',
-                ],
-            ),
         ],
         responses: [
             Response::HTTP_OK => [
                 'description' => 'User is currently logged in and has a valid session.',
                 'content' => [
-                    'application/vnd.ibexa.api.Session+xml' => [
-                        'schema' => [
-                            '$ref' => '#/components/schemas/Session',
-                        ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/Session.xml.example',
-                    ],
                     'application/vnd.ibexa.api.Session+json' => [
                         'schema' => [
                             '$ref' => '#/components/schemas/SessionWrapper',
                         ],
                         'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/session_id/refresh/POST/Session.json.example',
                     ],
+                    'application/vnd.ibexa.api.Session+xml' => [
+                        'schema' => [
+                            '$ref' => '#/components/schemas/Session',
+                        ],
+                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/Session.xml.example',
+                    ],
                 ],
             ],
             Response::HTTP_NOT_FOUND => [

src/lib/Server/Controller/Session/SessionCreateController.php

@@ -24,34 +24,17 @@
     uriTemplate: '/user/sessions',
     extraProperties: [OpenApiFactory::OVERRIDE_OPENAPI_RESPONSES => false],
     openapi: new Model\Operation(
+        operationId: 'ibexa.rest.create_session',
         summary: 'Create session (login a User)',
         description: 'Performs a login for the user or checks if session exists and returns the session and session cookie. The client will need to remember both session name/ID and CSRF token as this is for security reasons not exposed via GET.',
         tags: [
             'User Session',
         ],
         parameters: [
-            new Model\Parameter(
-                name: 'Accept',
-                in: 'header',
-                required: true,
-                description: 'If set, the session is returned in XML or JSON format.',
-                schema: [
-                    'type' => 'string',
-                ],
-            ),
-            new Model\Parameter(
-                name: 'Content-Type',
-                in: 'header',
-                required: true,
-                description: 'The SessionInput schema encoded in XML or JSON format.',
-                schema: [
-                    'type' => 'string',
-                ],
-            ),
             new Model\Parameter(
                 name: 'Cookie',
                 in: 'header',
-                required: true,
+                required: false,
                 description: 'Only needed for session\'s checking {sessionName}={sessionID}.',
                 schema: [
                     'type' => 'string',
@@ -60,61 +43,62 @@
             new Model\Parameter(
                 name: 'X-CSRF-Token',
                 in: 'header',
-                required: true,
-                description: 'Only needed for session\'s checking. The {csrfToken} needed on all unsafe HTTP methods with session.',
+                required: false,
+                description: 'Only needed for session\'s checking. The CSRF Token needed on all unsafe HTTP methods with session.',
                 schema: [
                     'type' => 'string',
                 ],
             ),
         ],
         requestBody: new Model\RequestBody(
+            description: 'The session input in XML or JSON format.',
             content: new \ArrayObject([
-                'application/vnd.ibexa.api.SessionInput+xml' => [
-                    'schema' => [
-                        '$ref' => '#/components/schemas/SessionInput',
-                    ],
-                    'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/SessionInput.xml.example',
-                ],
                 'application/vnd.ibexa.api.SessionInput+json' => [
                     'schema' => [
                         '$ref' => '#/components/schemas/SessionInputWrapper',
                     ],
                     'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/SessionInput.json.example',
                 ],
+                'application/vnd.ibexa.api.SessionInput+xml' => [
+                    'schema' => [
+                        '$ref' => '#/components/schemas/SessionInput',
+                    ],
+                    'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/SessionInput.xml.example',
+                ],
             ]),
         ),
         responses: [
             Response::HTTP_OK => [
                 'description' => 'Session already exists.',
                 'content' => [
-                    'application/vnd.ibexa.api.Session+xml' => [
+                    'application/vnd.ibexa.api.Session+json' => [
                         'schema' => [
-                            '$ref' => '#/components/schemas/Session',
+                            '$ref' => '#/components/schemas/SessionWrapper',
                         ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/Session.xml.example',
+                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/Session.json.example',
                     ],
-                    'application/vnd.ibexa.api.Session+json' => [
+                    'application/vnd.ibexa.api.Session+xml' => [
                         'schema' => [
-                            '$ref' => '#/components/schemas/SessionWrapper',
+                            '$ref' => '#/components/schemas/Session',
                         ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/session_id/refresh/POST/Session.json.example',
+                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/Session.xml.example',
                     ],
                 ],
             ],
             Response::HTTP_CREATED => [
                 'description' => 'Session is created.',
                 'content' => [
-                    'application/vnd.ibexa.api.Session+xml' => [
+                    'application/vnd.ibexa.api.Session+json' => [
                         'schema' => [
-                            '$ref' => '#/components/schemas/Session',
+                            '$ref' => '#/components/schemas/SessionWrapper',
                         ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/Session.xml.example',
+                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/Session.json.example',
                     ],
-                    'application/vnd.ibexa.api.Session+json' => [
+                    'application/vnd.ibexa.api.Session+xml' => [
                         'schema' => [
-                            '$ref' => '#/components/schemas/SessionWrapper',
+                            '$ref' => '#/components/schemas/Session',
                         ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/session_id/refresh/POST/Session.json.example',
+                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/Session.xml.example',
                     ],
                 ],
             ],

src/lib/Server/Controller/Session/SessionDeleteController.php

@@ -17,6 +17,7 @@
 #[Delete(
     uriTemplate: '/user/sessions/{sessionId}',
     openapi: new Model\Operation(
+        operationId: 'ibexa.rest.delete_session',
         summary: 'Delete session (logout a User)',
         description: 'The user session is removed i.e. the user is logged out.',
         tags: [
@@ -35,8 +36,8 @@
             new Model\Parameter(
                 name: 'X-CSRF-Token',
                 in: 'header',
-                required: true,
-                description: 'The {csrfToken} needed on all unsafe HTTP methods with session.',
+                required: false,
+                description: 'The CSRF Token needed on all unsafe HTTP methods with session.',
                 schema: [
                     'type' => 'string',
                 ],

src/lib/Server/Controller/Session/SessionRefreshController.php

@@ -19,6 +19,7 @@
     uriTemplate: '/user/sessions/{sessionId}/refresh',
     extraProperties: [OpenApiFactory::OVERRIDE_OPENAPI_RESPONSES => false],
     openapi: new Model\Operation(
+        operationId: 'ibexa.rest.refresh_session',
         summary: 'Refresh session (deprecated)',
         description: 'Get the session\'s User information. Deprecated as of Ibexa DXP 4.6, use GET /user/sessions/current instead.',
         tags: [
@@ -37,16 +38,8 @@
             new Model\Parameter(
                 name: 'X-CSRF-Token',
                 in: 'header',
-                required: true,
-                description: 'The {csrfToken} needed on all unsafe HTTP methods with session.',
-                schema: [
-                    'type' => 'string',
-                ],
-            ),
-            new Model\Parameter(
-                name: 'Accept',
-                in: 'header',
-                required: true,
+                required: false,
+                description: 'The CSRF Token needed on all unsafe HTTP methods with session.',
                 schema: [
                     'type' => 'string',
                 ],
@@ -60,30 +53,32 @@
                 ],
             ),
         ],
+        requestBody: new Model\RequestBody(
+            description: 'No payload required',
+            content: new \ArrayObject(),
+        ),
         responses: [
             Response::HTTP_OK => [
+                'description' => 'OK - returns the Session in XML or JSON format.',
                 'content' => [
-                    'application/vnd.ibexa.api.Session+xml' => [
-                        'schema' => [
-                            '$ref' => '#/components/schemas/Session',
-                        ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/Session.xml.example',
-                    ],
                     'application/vnd.ibexa.api.Session+json' => [
                         'schema' => [
                             '$ref' => '#/components/schemas/SessionWrapper',
                         ],
                         'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/session_id/refresh/POST/Session.json.example',
                     ],
+                    'application/vnd.ibexa.api.Session+xml' => [
+                        'schema' => [
+                            '$ref' => '#/components/schemas/Session',
+                        ],
+                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/session_id/refresh/POST/Session.xml.example',
+                    ],
                 ],
             ],
             Response::HTTP_NOT_FOUND => [
                 'description' => 'Error - the session does not exist.',
             ],
         ],
-        requestBody: new Model\RequestBody(
-            content: new \ArrayObject(),
-        ),
     ),
 )]
 /**

src/lib/Server/Controller/User/UserAssignToUserGroupController.php

@@ -22,17 +22,18 @@
     uriTemplate: '/user/users/{userId}/groups',
     extraProperties: [OpenApiFactory::OVERRIDE_OPENAPI_RESPONSES => false],
     openapi: new Model\Operation(
+        operationId: 'ibexa.rest.assign_user_to_user_group',
         summary: 'Assign User Group',
         description: 'Assigns the User to a User Group.',
         tags: [
             'User',
         ],
         parameters: [
             new Model\Parameter(
-                name: 'Accept',
+                name: 'X-CSRF-Token',
                 in: 'header',
                 required: true,
-                description: 'If set, the link list of User Groups is returned in XML or JSON format.',
+                description: 'The CSRF Token needed on all unsafe HTTP methods with session.',
                 schema: [
                     'type' => 'string',
                 ],
@@ -46,20 +47,25 @@
                 ],
             ),
         ],
+        requestBody: new Model\RequestBody(
+            description: 'No payload required',
+            content: new \ArrayObject(),
+        ),
         responses: [
             Response::HTTP_OK => [
+                'description' => 'If set, the link list of User Groups is returned in XML or JSON format.',
                 'content' => [
-                    'application/vnd.ibexa.api.UserGroupRefList+xml' => [
+                    'application/vnd.ibexa.api.UserGroupRefList+json' => [
                         'schema' => [
-                            '$ref' => '#/components/schemas/UserGroupRefList',
+                            '$ref' => '#/components/schemas/UserGroupRefListWrapper',
                         ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/users/user_id/groups/POST/UserGroupRefList.xml.example',
+                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/users/user_id/groups/POST/UserGroupRefList.json.example',
                     ],
-                    'application/vnd.ibexa.api.UserGroupRefList+json' => [
+                    'application/vnd.ibexa.api.UserGroupRefList+xml' => [
                         'schema' => [
-                            '$ref' => '#/components/schemas/UserGroupRefListWrapper',
+                            '$ref' => '#/components/schemas/UserGroupRefList',
                         ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/users/user_id/groups/group_id/UserGroupRefList.json.example',
+                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/users/user_id/groups/POST/UserGroupRefList.xml.example',
                     ],
                 ],
             ],
@@ -73,9 +79,6 @@
                 'description' => 'Error - the User does not exist.',
             ],
         ],
-        requestBody: new Model\RequestBody(
-            content: new \ArrayObject(),
-        ),
     ),
 )]
 final class UserAssignToUserGroupController extends UserBaseController