From 55e68e2fd5be7db40dafeb3dda5b692c4bafef00 Mon Sep 17 00:00:00 2001 From: Julian Lam Date: Mon, 13 Dec 2021 14:42:30 -0500 Subject: [PATCH] docs: openAPI documentation for routes --- public/openapi/write.yaml | 4 + public/openapi/write/chats.yaml | 165 ++++++++++++++++++++++++- public/openapi/write/chats/roomId.yaml | 17 +++ 3 files changed, 185 insertions(+), 1 deletion(-) create mode 100644 public/openapi/write/chats/roomId.yaml diff --git a/public/openapi/write.yaml b/public/openapi/write.yaml index 443b9866e6..9d7319bd80 100644 --- a/public/openapi/write.yaml +++ b/public/openapi/write.yaml @@ -136,6 +136,10 @@ paths: $ref: 'write/posts/pid/diffs/since.yaml' /posts/{pid}/diffs/{timestamp}: $ref: 'write/posts/pid/diffs/timestamp.yaml' + /chats/: + $ref: 'write/chats.yaml' + /chats/{roomId}: + $ref: 'write/chats/roomId.yaml' /flags/: $ref: 'write/flags.yaml' /flags/{flagId}: diff --git a/public/openapi/write/chats.yaml b/public/openapi/write/chats.yaml index 03deaad3ff..519b9f6556 100644 --- a/public/openapi/write/chats.yaml +++ b/public/openapi/write/chats.yaml @@ -1,3 +1,166 @@ +get: + tags: + - chats + summary: list recent chat rooms + description: This operation lists recently used chat rooms that the calling user is a part of + parameters: + - in: query + name: perPage + schema: + type: number + description: The number of chat rooms displayed per page + example: 20 + - in: query + name: page + schema: + type: number + description: The page number + example: 1 + responses: + '200': + description: chat rooms successfully listed + content: + application/json: + schema: + type: object + properties: + status: + $ref: ../components/schemas/Status.yaml#/Status + response: + allOf: + - $ref: ../components/schemas/Chats.yaml#/RoomObject + - type: object + properties: + unread: + type: boolean + description: Whether or not the chat has unread messages within + teaser: + type: object + nullable: true + properties: + fromuid: + type: number + content: + type: string + timestamp: + type: number + timestampISO: + type: string + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + displayname: + type: string + description: This is either username or fullname depending on forum and user settings + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + status: + type: string + lastonline: + type: number + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users + without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's + auto-generated icon + example: "#f44336" + lastonlineISO: + type: string + users: + type: array + items: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + displayname: + type: string + description: This is either username or fullname depending on forum and user settings + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + status: + type: string + lastonline: + type: number + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users + without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's + auto-generated icon + example: "#f44336" + lastonlineISO: + type: string + lastUser: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + displayname: + type: string + description: This is either username or fullname depending on forum and user settings + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + status: + type: string + lastonline: + type: number + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users + without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's + auto-generated icon + example: "#f44336" + lastonlineISO: + type: string + usernames: + type: string post: tags: - chats @@ -12,7 +175,7 @@ post: properties: uids: type: array - example: [2, 3] + example: [2] required: - uids responses: diff --git a/public/openapi/write/chats/roomId.yaml b/public/openapi/write/chats/roomId.yaml new file mode 100644 index 0000000000..c011c33825 --- /dev/null +++ b/public/openapi/write/chats/roomId.yaml @@ -0,0 +1,17 @@ +head: + tags: + - chats + summary: check if a chat room exists + parameters: + - in: path + name: roomId + schema: + type: number + required: true + description: room ID to check + example: 1 + responses: + '200': + description: chat room found + '404': + description: chat room not found \ No newline at end of file