diff --git a/docs/client-server/swagger_matrix/api-docs-rooms b/docs/client-server/swagger_matrix/api-docs-rooms
new file mode 100644
index 0000000000..7d3341f097
--- /dev/null
+++ b/docs/client-server/swagger_matrix/api-docs-rooms
@@ -0,0 +1,821 @@
+{
+ "apiVersion": "1.0.0",
+ "swaggerVersion": "1.2",
+ "basePath": "http://localhost:8080/_matrix/client/api/v1",
+ "resourcePath": "/rooms",
+ "produces": [
+ "application/json"
+ ],
+ "consumes": [
+ "application/json"
+ ],
+ "authorizations": {
+ "token": []
+ },
+ "apis": [
+ {
+ "path": "/rooms/{roomId}/send/{eventType}",
+ "operations": [
+ {
+ "method": "POST",
+ "summary": "Send a generic non-state event to this room.",
+ "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
+ "type": "EventId",
+ "nickname": "send_non_state_event",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "body",
+ "description": "The event contents",
+ "required": true,
+ "type": "EventContent",
+ "paramType": "body"
+ },
+ {
+ "name": "roomId",
+ "description": "The room to send the message in.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ },
+ {
+ "name": "eventType",
+ "description": "The type of event to send.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/state/{eventType}/{stateKey}",
+ "operations": [
+ {
+ "method": "PUT",
+ "summary": "Send a generic state event to this room.",
+ "notes": "The state key can be omitted, such that you can PUT to /rooms/{roomId}/state/{eventType}. The state key defaults to a 0 length string in this case.",
+ "type": "void",
+ "nickname": "send_state_event",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "body",
+ "description": "The event contents",
+ "required": true,
+ "type": "EventContent",
+ "paramType": "body"
+ },
+ {
+ "name": "roomId",
+ "description": "The room to send the message in.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ },
+ {
+ "name": "eventType",
+ "description": "The type of event to send.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ },
+ {
+ "name": "stateKey",
+ "description": "An identifier used to specify clobbering semantics. State events with the same (roomId, eventType, stateKey) will be replaced.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/send/m.room.message",
+ "operations": [
+ {
+ "method": "POST",
+ "summary": "Send a message in this room.",
+ "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
+ "type": "EventId",
+ "nickname": "send_message",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "body",
+ "description": "The message contents",
+ "required": true,
+ "type": "Message",
+ "paramType": "body"
+ },
+ {
+ "name": "roomId",
+ "description": "The room to send the message in.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/state/m.room.topic",
+ "operations": [
+ {
+ "method": "PUT",
+ "summary": "Set the topic for this room.",
+ "notes": "Set the topic for this room.",
+ "type": "void",
+ "nickname": "set_topic",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "body",
+ "description": "The topic contents",
+ "required": true,
+ "type": "Topic",
+ "paramType": "body"
+ },
+ {
+ "name": "roomId",
+ "description": "The room to set the topic in.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ]
+ },
+ {
+ "method": "GET",
+ "summary": "Get the topic for this room.",
+ "notes": "Get the topic for this room.",
+ "type": "Topic",
+ "nickname": "get_topic",
+ "parameters": [
+ {
+ "name": "roomId",
+ "description": "The room to get topic in.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ],
+ "responseMessages": [
+ {
+ "code": 404,
+ "message": "Topic not found."
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/send/m.room.message.feedback",
+ "operations": [
+ {
+ "method": "POST",
+ "summary": "Send feedback to a message.",
+ "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
+ "type": "EventId",
+ "nickname": "send_feedback",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "body",
+ "description": "The feedback contents",
+ "required": true,
+ "type": "Feedback",
+ "paramType": "body"
+ },
+ {
+ "name": "roomId",
+ "description": "The room to send the feedback in.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ],
+ "responseMessages": [
+ {
+ "code": 400,
+ "message": "Bad feedback type."
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/invite",
+ "operations": [
+ {
+ "method": "POST",
+ "summary": "Invite a user to this room.",
+ "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
+ "type": "void",
+ "nickname": "invite",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "roomId",
+ "description": "The room which has this user.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ },
+ {
+ "name": "body",
+ "description": "The user to invite.",
+ "required": true,
+ "type": "InviteRequest",
+ "paramType": "body"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/join",
+ "operations": [
+ {
+ "method": "POST",
+ "summary": "Join this room.",
+ "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
+ "type": "void",
+ "nickname": "join_room",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "roomId",
+ "description": "The room to join.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/leave",
+ "operations": [
+ {
+ "method": "POST",
+ "summary": "Leave this room.",
+ "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
+ "type": "void",
+ "nickname": "leave",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "roomId",
+ "description": "The room to leave.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/state/m.room.member/{userId}",
+ "operations": [
+ {
+ "method": "PUT",
+ "summary": "Change the membership state for a user in a room.",
+ "notes": "Change the membership state for a user in a room.",
+ "type": "void",
+ "nickname": "set_membership",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "body",
+ "description": "The new membership state",
+ "required": true,
+ "type": "Member",
+ "paramType": "body"
+ },
+ {
+ "name": "userId",
+ "description": "The user whose membership is being changed.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ },
+ {
+ "name": "roomId",
+ "description": "The room which has this user.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ],
+ "responseMessages": [
+ {
+ "code": 400,
+ "message": "No membership key."
+ },
+ {
+ "code": 400,
+ "message": "Bad membership value."
+ },
+ {
+ "code": 403,
+ "message": "When inviting: You are not in the room."
+ },
+ {
+ "code": 403,
+ "message": "When inviting: <target> is already in the room."
+ },
+ {
+ "code": 403,
+ "message": "When joining: Cannot force another user to join."
+ },
+ {
+ "code": 403,
+ "message": "When joining: You are not invited to this room."
+ }
+ ]
+ },
+ {
+ "method": "GET",
+ "summary": "Get the membership state of a user in a room.",
+ "notes": "Get the membership state of a user in a room.",
+ "type": "Member",
+ "nickname": "get_membership",
+ "parameters": [
+ {
+ "name": "userId",
+ "description": "The user whose membership state you want to get.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ },
+ {
+ "name": "roomId",
+ "description": "The room which has this user.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ],
+ "responseMessages": [
+ {
+ "code": 404,
+ "message": "Member not found."
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/join/{roomAliasOrId}",
+ "operations": [
+ {
+ "method": "PUT",
+ "summary": "Join a room via a room alias or room ID.",
+ "notes": "Join a room via a room alias or room ID.",
+ "type": "RoomInfo",
+ "nickname": "join",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "roomAliasOrId",
+ "description": "The room alias or room ID to join.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ],
+ "responseMessages": [
+ {
+ "code": 400,
+ "message": "Bad room alias."
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/createRoom",
+ "operations": [
+ {
+ "method": "POST",
+ "summary": "Create a room.",
+ "notes": "Create a room.",
+ "type": "RoomInfo",
+ "nickname": "create_room",
+ "consumes": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "body",
+ "description": "The desired configuration for the room. This operation can also be done as a PUT by suffixing /{txnId}.",
+ "required": true,
+ "type": "RoomConfig",
+ "paramType": "body"
+ }
+ ],
+ "responseMessages": [
+ {
+ "code": 400,
+ "message": "Body must be JSON."
+ },
+ {
+ "code": 400,
+ "message": "Room alias already taken."
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/messages",
+ "operations": [
+ {
+ "method": "GET",
+ "summary": "Get a list of messages for this room.",
+ "notes": "Get a list of messages for this room.",
+ "type": "MessagePaginationChunk",
+ "nickname": "get_messages",
+ "parameters": [
+ {
+ "name": "roomId",
+ "description": "The room to get messages in.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ },
+ {
+ "name": "from",
+ "description": "The token to start getting results from.",
+ "required": false,
+ "type": "string",
+ "paramType": "query"
+ },
+ {
+ "name": "to",
+ "description": "The token to stop getting results at.",
+ "required": false,
+ "type": "string",
+ "paramType": "query"
+ },
+ {
+ "name": "limit",
+ "description": "The maximum number of messages to return.",
+ "required": false,
+ "type": "integer",
+ "paramType": "query"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/members",
+ "operations": [
+ {
+ "method": "GET",
+ "summary": "Get a list of members for this room.",
+ "notes": "Get a list of members for this room.",
+ "type": "MemberPaginationChunk",
+ "nickname": "get_members",
+ "parameters": [
+ {
+ "name": "roomId",
+ "description": "The room to get a list of members from.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ },
+ {
+ "name": "from",
+ "description": "The token to start getting results from.",
+ "required": false,
+ "type": "string",
+ "paramType": "query"
+ },
+ {
+ "name": "to",
+ "description": "The token to stop getting results at.",
+ "required": false,
+ "type": "string",
+ "paramType": "query"
+ },
+ {
+ "name": "limit",
+ "description": "The maximum number of members to return.",
+ "required": false,
+ "type": "integer",
+ "paramType": "query"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/state",
+ "operations": [
+ {
+ "method": "GET",
+ "summary": "Get a list of all the current state events for this room.",
+ "notes": "Get a list of all the current state events for this room.",
+ "type": "array",
+ "items": {
+ "$ref": "Event"
+ },
+ "nickname": "get_state_events",
+ "parameters": [
+ {
+ "name": "roomId",
+ "description": "The room to get a list of current state events from.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "path": "/rooms/{roomId}/initialSync",
+ "operations": [
+ {
+ "method": "GET",
+ "summary": "Get all the current information for this room, including messages and state events.",
+ "notes": "Get all the current information for this room, including messages and state events.",
+ "type": "InitialSyncRoomData",
+ "nickname": "get_room_sync_data",
+ "parameters": [
+ {
+ "name": "roomId",
+ "description": "The room to get information for.",
+ "required": true,
+ "type": "string",
+ "paramType": "path"
+ }
+ ]
+ }
+ ]
+ }
+ ],
+ "models": {
+ "Topic": {
+ "id": "Topic",
+ "properties": {
+ "topic": {
+ "type": "string",
+ "description": "The topic text"
+ }
+ }
+ },
+ "Message": {
+ "id": "Message",
+ "properties": {
+ "msgtype": {
+ "type": "string",
+ "description": "The type of message being sent, e.g. \"m.text\"",
+ "required": true
+ },
+ "_msgtype_defined_keys_": {
+ "description": "Additional keys as defined by the msgtype, e.g. \"body\""
+ }
+ }
+ },
+ "Feedback": {
+ "id": "Feedback",
+ "properties": {
+ }
+ },
+ "Member": {
+ "id": "Member",
+ "properties": {
+ "membership": {
+ "type": "string",
+ "description": "Enum: The membership state of this member.",
+ "enum": [
+ "invite",
+ "join",
+ "leave",
+ "knock"
+ ]
+ }
+ }
+ },
+ "RoomInfo": {
+ "id": "RoomInfo",
+ "properties": {
+ "room_id": {
+ "type": "string",
+ "description": "The allocated room ID.",
+ "required": true
+ },
+ "room_alias": {
+ "type": "string",
+ "description": "The alias for the room.",
+ "required": false
+ }
+ }
+ },
+ "RoomConfig": {
+ "id": "RoomConfig",
+ "properties": {
+ "visibility": {
+ "type": "string",
+ "description": "Enum: The room visibility.",
+ "required": false,
+ "enum": [
+ "public",
+ "private"
+ ]
+ },
+ "room_alias_name": {
+ "type": "string",
+ "description": "The alias to give the new room.",
+ "required": false
+ }
+ }
+ },
+ "PaginationRequest": {
+ "id": "PaginationRequest",
+ "properties": {
+ "from": {
+ "type": "string",
+ "description": "The token to start getting results from."
+ },
+ "to": {
+ "type": "string",
+ "description": "The token to stop getting results at."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The maximum number of entries to return."
+ }
+ }
+ },
+ "PaginationChunk": {
+ "id": "PaginationChunk",
+ "properties": {
+ "start": {
+ "type": "string",
+ "description": "A token which correlates to the first value in \"chunk\" for paginating.",
+ "required": true
+ },
+ "end": {
+ "type": "string",
+ "description": "A token which correlates to the last value in \"chunk\" for paginating.",
+ "required": true
+ }
+ },
+ "subTypes": [
+ "MessagePaginationChunk"
+ ]
+ },
+ "MessagePaginationChunk": {
+ "id": "MessagePaginationChunk",
+ "properties": {
+ "chunk": {
+ "type": "array",
+ "description": "A list of message events.",
+ "items": {
+ "$ref": "MessageEvent"
+ },
+ "required": true
+ }
+ }
+ },
+ "MemberPaginationChunk": {
+ "id": "MemberPaginationChunk",
+ "properties": {
+ "chunk": {
+ "type": "array",
+ "description": "A list of member events.",
+ "items": {
+ "$ref": "MemberEvent"
+ },
+ "required": true
+ }
+ }
+ },
+ "Event": {
+ "id": "Event",
+ "properties": {
+ "event_id": {
+ "type": "string",
+ "description": "An ID which uniquely identifies this event. This is automatically set by the server.",
+ "required": true
+ },
+ "room_id": {
+ "type": "string",
+ "description": "The room in which this event occurred. This is automatically set by the server.",
+ "required": true
+ },
+ "type": {
+ "type": "string",
+ "description": "The event type.",
+ "required": true
+ }
+ },
+ "subTypes": [
+ "MessageEvent"
+ ]
+ },
+ "EventId": {
+ "id": "EventId",
+ "properties": {
+ "event_id": {
+ "type": "string",
+ "description": "The allocated event ID for this event.",
+ "required": true
+ }
+ }
+ },
+ "EventContent": {
+ "id": "EventContent",
+ "properties": {
+ "__event_content_keys__": {
+ "type": "string",
+ "description": "Event-specific content keys and values.",
+ "required": false
+ }
+ }
+ },
+ "MessageEvent": {
+ "id": "MessageEvent",
+ "properties": {
+ "content": {
+ "type": "Message"
+ }
+ }
+ },
+ "MemberEvent": {
+ "id": "MemberEvent",
+ "properties": {
+ "content": {
+ "type": "Member"
+ }
+ }
+ },
+ "InviteRequest": {
+ "id": "InviteRequest",
+ "properties": {
+ "user_id": {
+ "type": "string",
+ "description": "The fully-qualified user ID."
+ }
+ }
+ },
+ "InitialSyncRoomData": {
+ "id": "InitialSyncRoomData",
+ "properties": {
+ "membership": {
+ "type": "string",
+ "description": "This user's membership state in this room.",
+ "required": true
+ },
+ "room_id": {
+ "type": "string",
+ "description": "The ID of this room.",
+ "required": true
+ },
+ "messages": {
+ "type": "MessagePaginationChunk",
+ "description": "The most recent messages for this room, governed by the limit parameter.",
+ "required": false
+ },
+ "state": {
+ "type": "array",
+ "description": "A list of state events representing the current state of the room.",
+ "required": false,
+ "items": {
+ "$ref": "Event"
+ }
+ }
+ }
+ }
+ }
+}
|
