diff options
author | Sébastien Helleu <flashcode@flashtux.org> | 2024-05-15 21:20:22 +0200 |
---|---|---|
committer | Sébastien Helleu <flashcode@flashtux.org> | 2024-05-15 21:20:22 +0200 |
commit | 4c565413bb6516dc602542869bea0f2624282379 (patch) | |
tree | 9250155cd177588292f05ba7b04e960ab443eefb /src/plugins/relay | |
parent | b916ed6cf719e6001aca950719716afdb4e87215 (diff) | |
download | weechat-4c565413bb6516dc602542869bea0f2624282379.zip |
relay/api: add OpenAPI document (issue #2066)
Diffstat (limited to 'src/plugins/relay')
-rw-r--r-- | src/plugins/relay/api/weechat-relay-api.yaml | 996 |
1 files changed, 996 insertions, 0 deletions
diff --git a/src/plugins/relay/api/weechat-relay-api.yaml b/src/plugins/relay/api/weechat-relay-api.yaml new file mode 100644 index 000000000..1036fe1b1 --- /dev/null +++ b/src/plugins/relay/api/weechat-relay-api.yaml @@ -0,0 +1,996 @@ +openapi: 3.1.0 + +info: + title: WeeChat Relay API + description: |- + This is the [WeeChat](https://weechat.org/) Relay API based on the OpenAPI 3.1 specification. + + WeeChat specification: [Relay HTTP REST API](https://specs.weechat.org/specs/2023-005-relay-http-rest-api.html) + contact: + name: Sébastien Helleu + url: https://weechat.org + email: flashcode@flashtux.org + license: + name: CC BY-NC-SA 4.0 + url: https://creativecommons.org/licenses/by-nc-sa/4.0/ + version: 0.0.1 + +externalDocs: + url: https://weechat.org/doc/ + description: WeeChat documentation + +servers: + - url: https://localhost:9000/api + - url: http://localhost:9000/api + +tags: + - name: handshake + - name: version + - name: buffers + - name: hotlist + - name: input + - name: ping + - name: sync + +paths: + /handshake: + post: + tags: + - handshake + summary: Perform handshake + description: Perform handshake with remote WeeChat + operationId: handshake + requestBody: + $ref: '#/components/requestBodies/HandshakeBody' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Handshake' + '503': + description: Out of memory + /version: + get: + tags: + - version + summary: Get the version + description: Get the version + operationId: getVersion + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Version' + '401': + description: Unauthorized + '503': + description: Out of memory + security: + - password: [] + /buffers: + get: + tags: + - buffers + summary: Get buffers + description: Get a list of all buffers + operationId: getBuffers + parameters: + - $ref: '#/components/parameters/bufferLines' + - $ref: '#/components/parameters/bufferLinesFree' + - $ref: '#/components/parameters/bufferNicks' + - $ref: '#/components/parameters/colors' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Buffer' + '401': + description: Unauthorized + '503': + description: Out of memory + security: + - password: [] + /buffers/{buffer_id}: + get: + tags: + - buffers + summary: Get buffer by ID + operationId: getBufferById + parameters: + - $ref: '#/components/parameters/bufferId' + - $ref: '#/components/parameters/bufferLines' + - $ref: '#/components/parameters/bufferNicks' + - $ref: '#/components/parameters/colors' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Buffer' + '401': + description: Unauthorized + '404': + description: Buffer not found + '503': + description: Out of memory + security: + - password: [] + /buffers/{buffer_name}: + get: + tags: + - buffers + summary: Get buffer by full name + operationId: getBufferByName + parameters: + - $ref: '#/components/parameters/bufferName' + - $ref: '#/components/parameters/bufferLines' + - $ref: '#/components/parameters/bufferNicks' + - $ref: '#/components/parameters/colors' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Buffer' + '401': + description: Unauthorized + '404': + description: Buffer not found + '503': + description: Out of memory + security: + - password: [] + /buffers/{buffer_id}/lines: + get: + tags: + - buffers + summary: Get lines in a buffer + operationId: getBufferByIdLines + parameters: + - $ref: '#/components/parameters/bufferId' + - $ref: '#/components/parameters/bufferLines' + - $ref: '#/components/parameters/colors' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Line' + '401': + description: Unauthorized + '404': + description: Buffer not found + '503': + description: Out of memory + security: + - password: [] + /buffers/{buffer_id}/lines/{line_id}: + get: + tags: + - buffers + summary: Get a line in a buffer + operationId: getBufferByIdLineById + parameters: + - $ref: '#/components/parameters/bufferId' + - $ref: '#/components/parameters/lineId' + - $ref: '#/components/parameters/bufferLines' + - $ref: '#/components/parameters/colors' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Line' + '401': + description: Unauthorized + '404': + description: Buffer or line not found + '503': + description: Out of memory + security: + - password: [] + /buffers/{buffer_name}/lines: + get: + tags: + - buffers + summary: Get lines in a buffer + operationId: getBufferNameLines + parameters: + - $ref: '#/components/parameters/bufferName' + - $ref: '#/components/parameters/bufferLines' + - $ref: '#/components/parameters/colors' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Line' + '401': + description: Unauthorized + '404': + description: Buffer not found + '503': + description: Out of memory + security: + - password: [] + /buffers/{buffer_name}/lines/{line_id}: + get: + tags: + - buffers + summary: Get a line in a buffer + operationId: getBufferByNameLineById + parameters: + - $ref: '#/components/parameters/bufferName' + - $ref: '#/components/parameters/lineId' + - $ref: '#/components/parameters/bufferLines' + - $ref: '#/components/parameters/colors' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Line' + '401': + description: Unauthorized + '404': + description: Buffer or line not found + '503': + description: Out of memory + security: + - password: [] + /buffers/{buffer_id}/nicks: + get: + tags: + - buffers + summary: Get nicks in a buffer + operationId: getBufferByIdNicks + parameters: + - $ref: '#/components/parameters/bufferId' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/NickGroup' + '401': + description: Unauthorized + '404': + description: Buffer not found + '503': + description: Out of memory + security: + - password: [] + /buffers/{buffer_name}/nicks: + get: + tags: + - buffers + summary: Get nicks in a buffer + operationId: getBufferByNameNicks + parameters: + - $ref: '#/components/parameters/bufferName' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/NickGroup' + '401': + description: Unauthorized + '404': + description: Buffer not found + '503': + description: Out of memory + security: + - password: [] + /hotlist: + get: + tags: + - hotlist + summary: Get hotlist + operationId: getHotlist + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Hotlist' + '401': + description: Unauthorized + '400': + description: Bad request + '503': + description: Out of memory + security: + - password: [] + /input: + post: + tags: + - input + summary: Send text to a buffer + description: Send text to a buffer + operationId: input + requestBody: + $ref: '#/components/requestBodies/InputBody' + responses: + '204': + description: Successful operation + '400': + description: Bad request + '401': + description: Unauthorized + '404': + description: Buffer not found + security: + - password: [] + /ping: + post: + tags: + - ping + summary: Send ping request to WeeChat + description: Send ping request to WeeChat + operationId: ping + requestBody: + $ref: '#/components/requestBodies/PingBody' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Ping' + '204': + description: Successful operation + '401': + description: Unauthorized + '503': + description: Out of memory + security: + - password: [] + /sync: + post: + tags: + - sync + summary: Synchronize with WeeChat + description: Synchronize with WeeChat + operationId: sync + requestBody: + $ref: '#/components/requestBodies/SyncBody' + responses: + '204': + description: Successful operation + '401': + description: Unauthorized + '403': + description: Forbidden + security: + - password: [] + +components: + + parameters: + bufferId: + name: buffer_id + in: path + required: true + schema: + type: integer + format: int64 + description: Buffer identifier + bufferName: + name: buffer_name + in: path + required: true + schema: + type: string + description: >- + Buffer full name + example: 'irc.libera.#weechat' + lineId: + name: line_id + in: path + required: true + schema: + type: integer + format: int64 + description: Line identifier + bufferLines: + name: lines + in: query + required: false + schema: + type: integer + format: int64 + default: 0 + description: | + Number of lines to return: + * negative number: return N lines from the end of buffer (newest lines) + * `0`: do not return any line + * positive number: return N lines from the beginning of buffer (oldest lines) + bufferLinesFree: + name: lines_free + in: query + required: false + schema: + type: integer + format: int64 + default: 0 + description: | + Number of lines to return in buffers with free content: + * negative number: return N lines from the end of buffer (newest lines) + * `0`: do not return any line + * positive number: return N lines from the beginning of buffer (oldest lines) + + Default value is `0` if "lines" is set to 0, otherwise all lines are returned. + bufferNicks: + name: nicks + in: query + required: false + schema: + type: boolean + default: false + description: Return buffer nicklist (groups and nicks) + colors: + name: colors + in: query + required: false + schema: + type: string + enum: + - ansi + - weechat + - strip + default: ansi + description: | + How to return strings with color codes: + * `ansi`: return ANSI color codes + * `weechat`: return WeeChat internal color codes + * `strip`: strip colors + + schemas: + Handshake: + type: object + properties: + password_hash_algo: + type: string + nullable: true + enum: + - plain + - sha256 + - sha512 + - pbkdf2+sha256 + - pbkdf2+sha512 + example: pbkdf2+sha512 + password_hash_iterations: + type: integer + format: int32 + example: 100000 + totp: + type: boolean + example: true + required: + - password_hash_algo + - password_hash_iterations + - totp + Version: + type: object + properties: + weechat_version: + type: string + example: 4.3.0-dev + weechat_version_git: + type: string + example: v4.2.0-360-gccf23ae51 + weechat_version_number: + type: integer + format: int32 + example: 67305472 + relay_api_version: + type: string + example: "0.0.1" + relay_api_version_number: + type: integer + format: int32 + example: 1 + required: + - weechat_version + - weechat_version_git + - weechat_version_number + - relay_api_version + - relay_api_version_number + Buffer: + type: object + properties: + id: + type: integer + format: int64 + description: buffer identifier (≥ 0) + example: 1709932823238637 + name: + type: string + example: 'irc.libera.#weechat' + short_name: + type: string + example: '#weechat' + number: + type: integer + format: int64 + description: buffer number (≥ 1) + example: 3 + type: + type: string + enum: + - formatted + - free + description: the buffer type + example: formatted + title: + type: string + description: the buffer title (can contain colors) + example: 'Welcome to the WeeChat official support channel' + modes: + type: string + description: the buffer modes (can contain colors) + example: '+nt' + input_prompt: + type: string + description: the input prompt (can contain colors) + example: '[@alice(i)]' + input: + type: string + description: the buffer input + example: '' + input_position: + type: integer + format: int32 + description: position in input (number of UTF-8 chars, ≥ 0) + example: 0 + input_multiline: + type: boolean + description: buffers allows multiline input + example: false + nicklist: + type: boolean + description: buffer has a nicklist + example: true + nicklist_case_sensitive: + type: boolean + description: groups and nicks are case sensitive + example: false + nicklist_display_groups: + type: boolean + description: groups are displayed in nicklist + example: false + local_variables: + type: object + description: the buffer local variables + example: + plugin: 'irc' + name: 'libera.#weechat' + type: 'channel' + server: 'libera' + channel: '#weechat' + nick: 'alice' + host: '~alice@example.com' + keys: + type: array + items: + $ref: '#/components/schemas/Key' + lines: + type: array + items: + $ref: '#/components/schemas/Line' + nicklist_root: + $ref: '#/components/schemas/NickGroup' + required: + - id + - name + - short_name + - number + - type + - title + - modes + - input_prompt + - input + - input_position + - input_multiline + - nicklist + - nicklist_case_sensitive + - nicklist_display_groups + - local_variables + - keys + Key: + type: object + properties: + key: + type: string + description: key name + example: meta-f,meta-a + command: + type: string + description: command + example: '/fset -append' + required: + - key + - command + Line: + type: object + properties: + id: + type: integer + format: int64 + description: line identifier (≥ 0, unique in buffer) + example: 0 + y: + type: integer + format: int64 + description: line index (≥ 1) on free buffer, -1 on formatted buffer + example: -1 + date: + type: string + format: date-time + description: date and time of line + example: '"2023-12-05T19:46:03.847625Z' + date_printed: + type: string + format: date-time + description: date and time when the line was printed + example: '2023-12-05T19:46:03.847625Z' + highlight: + type: boolean + description: line has a highlight + example: false + notify_level: + type: integer + format: int32 + description: | + Notify level: + * -1: no notify at all + * 0: low + * 1: message + * 2: private message + * 3: message with highlight + example: 0 + prefix: + type: string + description: prefix displayed before the message (can contain colors) + example: '-->' + message: + type: string + description: the message (can contain colors) + example: 'alice (~alice@example.com) has joined #test' + tags: + items: + type: string + description: tags + example: + - 'irc_join' + - 'irc_tag_account=alice' + - 'irc_tag_time=2023-12-05T19:46:03.847Z' + - 'nick_alice' + - 'host_~alice@example.com' + - 'log4' + required: + - id + - y + - date + - date_printed + - highlight + - notify_level + - prefix + - message + - tags + NickGroup: + type: object + properties: + id: + type: integer + format: int64 + description: group identifier (≥ 0, unique in buffer) + example: 1709932823649181 + parent_group_id: + type: integer + format: int64 + description: parent group identifier, -1 if group is the root of nicklist + example: 1709932823145768 + name: + type: string + description: group name + example: "root" + color_name: + type: string + description: group color name (can be an option or color name) + example: 'weechat.color.nicklist_group' + color: + type: string + description: group color + example: '\u001b[32m' + visible: + type: boolean + description: the group is displayed + example: true + groups: + type: array + items: + $ref: '#/components/schemas/NickGroup' + nicks: + type: array + items: + $ref: '#/components/schemas/Nick' + example: + id: 0 + parent_group_id: -1 + name: 'root' + color_name: '' + color: '' + visible: false + groups: + - id: 1709932823649181 + parent_group_id: 0 + name: '000|o' + color_name: 'weechat.color.nicklist_group' + color: '\u001b[32m' + visible: true + groups: [] + nicks: + - id: 1709932823649184 + parent_group_id: 1709932823649181 + prefix: '@' + prefix_color_name: 'lightgreen' + prefix_color: '\u001b[92m' + name: 'alice' + color_name: 'bar_fg' + color: '' + visible: true + - id: 1709932823649189 + parent_group_id: 0 + name: '001|h' + color_name: 'weechat.color.nicklist_group' + color: '\u001b[32m' + visible: true + groups: [] + nicks: [] + - id: 1709932823649203 + parent_group_id: 0 + name: '002|v' + color_name: 'weechat.color.nicklist_group' + color: '\u001b[32m' + visible: true + groups: [] + nicks: [] + - id: 1709932823649210 + parent_group_id: 0 + name: '999|...' + color_name: 'weechat.color.nicklist_group' + color: '\u001b[32m' + visible: true + groups: [] + nicks: [] + nicks: [] + required: + - id + - parent_group_id + - name + - color_name + - color + - visible + - groups + - nicks + Nick: + type: object + properties: + id: + type: integer + format: int64 + description: group identifier (≥ 0, unique in buffer) + example: 1709932823649181 + parent_group_id: + type: integer + format: int64 + description: parent group identifier, -1 if group is the root of nicklist + example: 1709932823145768 + prefix: + type: string + description: nick prefix + example: "@" + prefix_color_name: + type: string + description: prefix color name (can be an option or color name) + example: 'lightgreen' + prefix_color: + type: string + description: prefix color + example: '\u001b[32m' + name: + type: string + description: nick name + example: "alice" + color_name: + type: string + description: nick color name (can be an option or color name) + example: 'bar_fg' + color: + type: string + description: nick color + example: '' + visible: + type: boolean + description: the nick is displayed + example: true + required: + - id + - parent_group_id + - prefix + - prefix_color_name + - prefix_color + - name + - color_name + - color + - visible + Hotlist: + type: object + properties: + priority: + type: integer + format: int32 + description: | + Priority of the hotlist entry: + * `0`: low + * `1`: message + * `2`: private + * `3`: highlight + example: 1 + date: + type: string + format: date-time + description: date and time of the hotlist entry + example: '2024-03-17T16:38:51.572834Z' + buffer_id: + type: integer + format: int64 + description: buffer identifier + example: 1709932823238637 + count: + type: array + items: + type: integer + minItems: 4 + maxItems: 4 + example: + - 44 + - 3 + - 0 + - 1 + required: + - priority + - date + - buffer_id + - count + Ping: + type: object + properties: + data: + type: string + example: 1714854355123456 + required: + - data + + requestBodies: + HandshakeBody: + description: Handshake request + required: false + content: + application/json: + schema: + type: object + properties: + password_hash_algo: + type: array + items: + type: string + enum: + - plain + - sha256 + - sha512 + - pbkdf2+sha256 + - pbkdf2+sha512 + example: + - plain + - sha256 + - sha512 + - pbkdf2+sha256 + - pbkdf2+sha512 + InputBody: + description: Buffer and command to execute + required: true + content: + application/json: + schema: + type: object + properties: + buffer_id: + type: integer + format: int64 + description: Buffer identifier (≥ 0) + example: 1709932823238637 + buffer: + type: string + description: >- + Buffer full name (eg: `irc.libera.#weechat`) + example: 'irc.libera.#weechat' + command: + type: string + description: text or command to send + example: 'hello, world!' + required: + - command + PingBody: + description: Custom data that will be returned in the response + required: false + content: + application/json: + schema: + type: object + properties: + data: + type: string + example: 1714854355123456 + SyncBody: + description: Synchronization parameters + required: false + content: + application/json: + schema: + type: object + properties: + sync: + type: boolean + description: Enable synchronization + example: true + nicks: + type: boolean + description: Receive nick updates in buffers + example: true + input: + type: boolean + description: Receive input changes in buffers (content and cursor position) + example: true + colors: + type: string + enum: + - ansi + - weechat + - strip + default: ansi + description: | + How to return strings with color codes: + * `ansi`: return ANSI color codes + * `weechat`: return WeeChat internal color codes + * `strip`: strip colors + + securitySchemes: + password: + type: http + scheme: basic |