Improve rooms API reference (#1788)

* Improve rooms API reference

* review comments

packages/api/src/controllers/room.ts

@@ -259,7 +259,7 @@ app.get("/:roomId/user/:participantId", authorizer({}), async (req, res) => {
  res.json({
  id: participant.identity,
  state: participant.state,
- joinedAt: participant.joinedAt,
+ joinedAt: participant.joinedAt * 1000,
  name: participant.name,
  permission: participant.permission,
  isPublisher: participant.isPublisher,

packages/api/src/schema/api-schema.yaml

@@ -1033,9 +1033,58 @@ components:
  properties:
  name:
  type: string
+ description: Display name
+ example: name
  canPublish:
  type: boolean
  description: Whether a user is allowed to publish audio/video tracks
+ example: true
+ create-room-response:
+ type: object
+ properties:
+ id:
+ type: string
+ description: The ID of the room
+ example: d32ae9e6-c459-4931-9898-e86e2f5e7e16
+ room-user-response:
+ type: object
+ properties:
+ id:
+ type: string
+ description: The ID of the user
+ example: d32ae9e6-c459-4931-9898-e86e2f5e7e16
+ joinUrl:
+ type: string
+ description:
+ Joining URL - use this for Livepeer's default meeting app (see the
+ multiparticipant streaming guide for more info).
+ example: https://meet.livepeer.chat
+ token:
+ type: string
+ description:
+ Joining JWT - this can be used if you have a custom meeting app (see
+ the multiparticipant streaming guide for more info).
+ example: token
+ get-room-user-response:
+ type: object
+ properties:
+ id:
+ type: string
+ description: The ID of the user
+ example: d32ae9e6-c459-4931-9898-e86e2f5e7e16
+ joinedAt:
+ type: integer
+ description: Timestamp (in milliseconds) at which the user joined
+ example: 1687517025261
+ name:
+ type: string
+ description: The display name of the user
+ example: name
+ isPublisher:
+ type: boolean
+ description: Whether a user is allowed to publish audio/video tracks
+ example: true
+ default: true
  room-egress-payload:
  type: object
  required:
@@ -1045,6 +1094,7 @@ components:
  streamId:
  type: string
  description: The ID of the Livepeer Stream to stream to
+ example: aac12556-4d65-4d34-9fb6-d1f0985eb0a9
  room-user-update-payload:
  type: object
  required:
@@ -1054,6 +1104,8 @@ components:
  canPublish:
  type: boolean
  description: Whether a user is allowed to publish audio/video tracks
+ example: true
+ default: true
  transcode-payload:
  additionalProperties: false
  required:
@@ -1746,6 +1798,7 @@ components:
  type: string
  readOnly: true
  description: room ID
+ example: d32ae9e6-c459-4931-9898-e86e2f5e7e16
  createdAt:
  type: number
  readOnly: true
@@ -1759,16 +1812,6 @@ components:
  egressId:
  type: string
  description: internal ID for egress output
- events:
- type: array
- items:
- type: object
- additionalProperties: false
- properties:
- eventName:
- type: string
- timestamp:
- type: integer
  participants:
  type: object
  additionalProperties:
@@ -2896,11 +2939,7 @@ paths:
  content:
  application/json:
  schema:
- type: object
- additionalProperties: false
- properties:
- id:
- type: string
+ $ref: "#/components/schemas/create-room-response"
  default:
  description: Error
  content:
@@ -2971,13 +3010,13 @@ paths:
  schema:
  $ref: "#/components/schemas/error"
  delete:
+ summary: Stop room RTMP egress
  parameters:
  - name: id
  in: path
  required: true
  schema:
  type: string
- summary: Stop room RTMP egress
  responses:
  "204":
  description: Success
@@ -3003,6 +3042,12 @@ paths:
  type: string
  summary: Create a room user
  responses:
+ "201":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/room-user-response"
  default:
  description: Error
  content:
@@ -3029,16 +3074,7 @@ paths:
  content:
  application/json:
  schema:
- type: object
- properties:
- id:
- type: string
- joinedAt:
- type: integer
- name:
- type: string
- isPublisher:
- type: boolean
+ $ref: "#/components/schemas/get-room-user-response"
  default:
  description: Error
  content:
@@ -3063,7 +3099,7 @@ paths:
  required: true
  schema:
  type: string
- summary: Update a users permissions
+ summary: Update a room user
  responses:
  "204":
  description: Success

packages/api/src/schema/db-schema.yaml

@@ -1131,6 +1131,19 @@ components:
  type: number
  description: Timestamp (in milliseconds) at which the room was deleted
  example: 1587667174725
+ events:
+ type: array
+ items:
+ type: object
+ additionalProperties: false
+ properties:
+ eventName:
+ type: string
+ example: event name
+ timestamp:
+ type: integer
+ description: Event timestamp (in milliseconds)
+ example: 1587667174725
  participants:
  type: object
  additionalProperties: