Mercurial > prosody-modules
changeset 4476:125279f4a5b8
mod_rest: Restructure API spec
To make referencing individual fields easier, apparently some things
don't like references to individual properties of an object.
| author | Kim Alvefur <zash@zash.se> |
|---|---|
| date | Sun, 28 Feb 2021 18:55:18 +0100 |
| parents | 017ad6ed96ae |
| children | 8df6cc648963 |
| files | mod_rest/openapi.yaml |
| diffstat | 1 files changed, 323 insertions(+), 267 deletions(-) [+] |
line wrap: on
line diff
--- a/mod_rest/openapi.yaml Sat Feb 27 02:37:01 2021 +0100 +++ b/mod_rest/openapi.yaml Sun Feb 28 18:55:18 2021 +0100 @@ -67,296 +67,352 @@ stanza: properties: delay: - type: string - description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082 - format. + $ref: '#/components/schemas/delay' state: - enum: - - active - - inactive - - gone - - composing - - paused - description: Chat state notifications, e.g. "is typing..." - type: string - example: composing - thread: - type: string - description: Message thread identifier + $ref: '#/components/schemas/state' + type: + $ref: '#/components/schemas/type' status: - type: string - description: Textual status message. + $ref: '#/components/schemas/status' id: - type: string - description: Reasonably unique id. mod_rest generates one if left out. + $ref: '#/components/schemas/id' replace: - type: string - description: ID of message being replaced (e.g. for corrections) + $ref: '#/components/schemas/replace' from: - description: the sender - type: string - example: bob@localhost.example + $ref: '#/components/schemas/from' body: - description: Human-readable chat message - type: string - example: Hello, World! - command: - oneOf: - - type: string - - type: object - properties: - data: - $ref: '#/components/schemas/stanza/properties/formdata' - action: - type: string - note: - type: object - properties: - text: - type: string - type: - type: string - enum: - - info - - warn - - error - form: - $ref: '#/components/schemas/stanza/properties/dataform' - sessionid: - type: string - status: - type: string - node: - type: string - actions: - type: object - properties: - complete: - type: boolean - prev: - type: boolean - next: - type: boolean - execute: - type: string - description: Ad-hoc commands. + $ref: '#/components/schemas/body' + kind: + $ref: '#/components/schemas/kind' show: - description: indicator of availability, ie away or not - type: string - enum: - - away - - chat - - dnd - - xa + $ref: '#/components/schemas/show' stats: - description: Statistics - type: array - items: - type: object - properties: - name: - type: string - unit: - type: string - value: - type: string + $ref: '#/components/schemas/stats' priority: - type: string - description: presence priority - kind: - description: Which kind of stanza - type: string - enum: - - message - - presence - - iq + $ref: '#/components/schemas/priority' + nick: + $ref: '#/components/schemas/nick' to: - description: recipient - type: string - example: alice@example.com - type: - description: Stanza type - type: string - enum: - - chat - - normal - - headline - - groupchat - - get - - set - - result - - available - - unavailable - - subscribe - - subscribed - - unsubscribe - - unsubscribed + $ref: '#/components/schemas/to' + ping: + $ref: '#/components/schemas/ping' + subject: + $ref: '#/components/schemas/subject' lang: - description: Language code - type: string - example: en - formdata: - additionalProperties: - oneOf: - - type: string - - type: array - items: - type: string - type: object - description: Simplified data form + $ref: '#/components/schemas/lang' join: - description: For joining Multi-User-Chats - type: boolean - enum: - - true + $ref: '#/components/schemas/join' + html: + $ref: '#/components/schemas/html' dataform: - properties: - title: - type: string - fields: - type: array - items: - type: object - properties: - value: - oneOf: - - type: string - - type: array - items: - type: string - type: - type: string - label: - type: string - desc: - type: string - required: - type: boolean - var: - type: string - type: - type: string - enum: - - form - - submit - - cancel - - result - instructions: - type: string - description: Data form - type: object - items: - oneOf: - - description: An items query or empty list - type: boolean - enum: - - true - - type: string - description: A query with a node, or an empty reply list with a node - - description: List of items referenced - type: array - items: - properties: - jid: - type: string - description: Address of item - node: - type: string - name: - type: string - description: Descriptive name - required: - - jid - type: object - description: List of references to other entities + $ref: '#/components/schemas/dataform' version: - oneOf: - - type: boolean - - properties: - version: - type: string - name: - type: string - os: - type: string - required: - - name - - version - type: object - description: Software version query + $ref: '#/components/schemas/version' payload: - required: - - datatype - - data - properties: - data: - type: object - datatype: - type: string - description: A piece of arbitrary JSON with a type field attached - type: object + $ref: '#/components/schemas/payload' disco: - oneOf: - - type: boolean - description: Either a query, or an empty response - - type: string - description: A query with a node, or an empty response with a node - - properties: - features: - description: List of URIs indicating supported features - type: array - items: - type: string - identities: - items: - type: object - properties: - name: - type: string - type: - type: string - category: - type: string - description: List of abstract identities or types that describe the - entity - type: array - example: - - name: Prosody - type: im - category: server - node: - type: string - extensions: - type: object - description: A full response - type: object - description: Discover supported features + $ref: '#/components/schemas/disco' oob_url: - type: string - description: URL of an attached media file. - html: - description: HTML version of 'body' - type: string - example: <body><p>Hello!</p></body> - subject: - description: Subject of message or group chat - type: string - example: Talking about stuff - ping: - description: A ping. - type: boolean - enum: - - true - nick: - type: string - description: Nickname of the sender + $ref: '#/components/schemas/oob_url' + items: + $ref: '#/components/schemas/items' + formdata: + $ref: '#/components/schemas/formdata' + thread: + $ref: '#/components/schemas/thread' + command: + $ref: '#/components/schemas/command' type: object example: body: Hello type: chat kind: message + to: alice@example.com state: active - to: alice@example.com + delay: + type: string + description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082 + format. + state: + enum: + - active + - inactive + - gone + - composing + - paused + description: Chat state notifications, e.g. "is typing..." + type: string + example: composing + thread: + type: string + description: Message thread identifier + status: + type: string + description: Textual status message. + id: + type: string + description: Reasonably unique id. mod_rest generates one if left out. + replace: + type: string + description: ID of message being replaced (e.g. for corrections) + from: + description: the sender + type: string + example: bob@localhost.example + body: + description: Human-readable chat message + type: string + example: Hello, World! + command: + oneOf: + - type: string + - type: object + properties: + data: + $ref: '#/components/schemas/stanza/properties/formdata' + action: + type: string + note: + type: object + properties: + text: + type: string + type: + type: string + enum: + - info + - warn + - error + form: + $ref: '#/components/schemas/stanza/properties/dataform' + sessionid: + type: string + status: + type: string + node: + type: string + actions: + type: object + properties: + complete: + type: boolean + prev: + type: boolean + next: + type: boolean + execute: + type: string + description: Ad-hoc commands. + show: + description: indicator of availability, ie away or not + type: string + enum: + - away + - chat + - dnd + - xa + stats: + description: Statistics + type: array + items: + type: object + properties: + name: + type: string + unit: + type: string + value: + type: string + priority: + type: string + description: presence priority + kind: + description: Which kind of stanza + type: string + enum: + - message + - presence + - iq + to: + description: recipient + type: string + example: alice@example.com + type: + description: Stanza type + type: string + enum: + - chat + - normal + - headline + - groupchat + - get + - set + - result + - available + - unavailable + - subscribe + - subscribed + - unsubscribe + - unsubscribed + lang: + description: Language code + type: string + example: en + formdata: + additionalProperties: + oneOf: + - type: string + - type: array + items: + type: string + type: object + description: Simplified data form + join: + description: For joining Multi-User-Chats + type: boolean + enum: + - true + dataform: + properties: + title: + type: string + fields: + type: array + items: + type: object + properties: + value: + oneOf: + - type: string + - type: array + items: + type: string + type: + type: string + label: + type: string + desc: + type: string + required: + type: boolean + var: + type: string + type: + type: string + enum: + - form + - submit + - cancel + - result + instructions: + type: string + description: Data form + type: object + items: + oneOf: + - description: An items query or empty list + type: boolean + enum: + - true + - type: string + description: A query with a node, or an empty reply list with a node + - description: List of items referenced + type: array + items: + properties: + jid: + type: string + description: Address of item + node: + type: string + name: + type: string + description: Descriptive name + required: + - jid + type: object + description: List of references to other entities + version: + oneOf: + - type: boolean + - properties: + version: + type: string + name: + type: string + os: + type: string + required: + - name + - version + type: object + description: Software version query + payload: + required: + - datatype + - data + properties: + data: + type: object + datatype: + type: string + description: A piece of arbitrary JSON with a type field attached + type: object + disco: + oneOf: + - type: boolean + description: Either a query, or an empty response + - type: string + description: A query with a node, or an empty response with a node + - properties: + features: + description: List of URIs indicating supported features + type: array + items: + type: string + identities: + items: + type: object + properties: + name: + type: string + type: + type: string + category: + type: string + description: List of abstract identities or types that describe the + entity + type: array + example: + - name: Prosody + type: im + category: server + node: + type: string + extensions: + type: object + description: A full response + type: object + description: Discover supported features + oob_url: + type: string + description: URL of an attached media file. + html: + description: HTML version of 'body' + type: string + example: <body><p>Hello!</p></body> + subject: + description: Subject of message or group chat + type: string + example: Talking about stuff + ping: + description: A ping. + type: boolean + enum: + - true + nick: + type: string + description: Nickname of the sender securitySchemes: token: description: Tokens from mod_http_oauth2.