backend: Add room fields parameter and enhance success responses in OpenAPI documentation

backend/openapi/components/parameters/room-fields.yaml

@@ -0,0 +1,9 @@
+name: fields
+in: query
+description: >
+    The fields to retrieve from the room.
+    Comma-separated list of fields to include in the response.
+required: false
+schema:
+    type: string
+    example: 'room-123'

backend/openapi/components/responses/success-create-room.yaml

@@ -1,4 +1,4 @@
-description: Success room response
+description: Success response for creating a room
 content:
     application/json:
         schema:

backend/openapi/components/responses/success-get-room.yaml

@@ -0,0 +1,45 @@
+description: Success response for retrieving a room
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/meet-room.yaml'
+        examples:
+            complete_room_details:
+                summary: Full room details response
+                value:
+                    roomId: 'room-123'
+                    roomIdPrefix: 'room'
+                    creationDate: 1620000000000
+                    expirationDate: 1620000800000
+                    preferences:
+                        chatPreferences:
+                            enabled: true
+                        recordingPreferences:
+                            enabled: false
+                        virtualBackgroundPreferences:
+                            enabled: true
+                    moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                    publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+
+            roomId_fields_only:
+                summary: Response with only the roomId
+                value:
+                    roomId: 'room-123'
+
+            no_urls:
+                summary: Room details including preferences but no URLs
+                value:
+                    roomId: 'room-123'
+                    preferences:
+                        chatPreferences:
+                            enabled: true
+                        recordingPreferences:
+                            enabled: false
+                        virtualBackgroundPreferences:
+                            enabled: true
+
+            urls_only:
+                summary: Response containing only moderator and publisher URLs
+                value:
+                    moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                    publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'

backend/openapi/components/responses/success-get-rooms.yaml

@@ -15,5 +15,82 @@ content:
                             type: boolean
                             description: Indicates if there are more rooms to retrieve.
                         nextPageToken:
-                            type: string
+                            type: [string, 'null']
                             description: The token to retrieve the next page of rooms.
+
+        examples:
+            complete_room_details:
+                summary: Full room details response with multiple rooms
+                value:
+                    rooms:
+                        - roomId: 'room-123'
+                          roomIdPrefix: 'room'
+                          creationDate: 1620000000000
+                          expirationDate: 1620000800000
+                          preferences:
+                              chatPreferences:
+                                  enabled: true
+                              recordingPreferences:
+                                  enabled: false
+                              virtualBackgroundPreferences:
+                                  enabled: true
+                          moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                          publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                        - roomId: 'room-456'
+                          roomIdPrefix: 'room'
+                          creationDate: 1620001000000
+                          expirationDate: 1620001800000
+                          preferences:
+                              chatPreferences:
+                                  enabled: false
+                              recordingPreferences:
+                                  enabled: true
+                              virtualBackgroundPreferences:
+                                  enabled: false
+                          moderatorURL: 'http://localhost:6080/room/room-456/?secret=tok_789012'
+                          publisherURL: 'http://localhost:6080/room/room-456/?secret=tok_789012'
+                    pagination:
+                        isTruncated: false
+            roomId_fields_only:
+                summary: Response with only roomId for each room
+                value:
+                    rooms:
+                        - roomId: 'room-123'
+                        - roomId: 'room-456'
+                    pagination:
+                        isTruncated: false
+
+            no_urls:
+                summary: Room details including preferences but no URLs
+                value:
+                    rooms:
+                        - roomId: 'room-123'
+                          preferences:
+                              chatPreferences:
+                                  enabled: true
+                              recordingPreferences:
+                                  enabled: false
+                              virtualBackgroundPreferences:
+                                  enabled: true
+                        - roomId: 'room-456'
+                          preferences:
+                              chatPreferences:
+                                  enabled: false
+                              recordingPreferences:
+                                  enabled: true
+                              virtualBackgroundPreferences:
+                                  enabled: false
+                    pagination:
+                        isTruncated: true
+                        nextPageToken: 'abc123'
+
+            urls_only:
+                summary: Response containing only moderator and publisher URLs
+                value:
+                    rooms:
+                        - moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                          publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                        - moderatorURL: 'http://localhost:6080/room/room-456/?secret=tok_789012'
+                          publisherURL: 'http://localhost:6080/room/room-456/?secret=tok_789012'
+                    pagination:
+                        isTruncated: false

backend/openapi/paths/rooms.yaml

@@ -35,6 +35,7 @@
             - apiKeyInHeader: []
             - accessTokenCookie: []
         parameters:
+            - $ref: '../components/parameters/room-fields.yaml'
             - $ref: '../components/parameters/max-items.yaml'
             - $ref: '../components/parameters/next-page-token.yaml'
         responses:
@@ -60,9 +61,11 @@
             - participantTokenCookie: []
         parameters:
             - $ref: '../components/parameters/room-id.yaml'
+            - $ref: '../components/parameters/room-fields.yaml'
         responses:
             '200':
-                $ref: '../components/responses/success-create-room.yaml'
+                $ref: '../components/responses/success-get-room.yaml'
+
             '401':
                 $ref: '../components/responses/unauthorized-error.yaml'
             '403':