Software / code / prosody-modules
Changeset
5527:5268049915d8
mod_rest: Apply normalization to openapi spec
Using https://github.com/mikefarah/yq v4.34.1 --prettyPrint
| author | Kim Alvefur <zash@zash.se> |
|---|---|
| date | Wed, 07 Jun 2023 15:52:02 +0200 |
| parents | 5526:46e512f4ba14 |
| children | 5528:ce6e071d61a0 |
| files | mod_rest/res/openapi.yaml |
| diffstat | 1 files changed, 276 insertions(+), 375 deletions(-) [+] |
line wrap: on
line diff
--- a/mod_rest/res/openapi.yaml Wed Jun 07 12:54:52 2023 +0200 +++ b/mod_rest/res/openapi.yaml Wed Jun 07 15:52:02 2023 +0200 @@ -1,6 +1,5 @@ --- openapi: 3.0.1 - info: title: mod_rest API version: 0.3.2 @@ -10,14 +9,12 @@ and a simplified JSON mapping. license: name: MIT - paths: - /rest: post: summary: Send stanzas and receive responses. Webhooks work the same way. tags: - - generic + - generic security: - basic: [] - token: [] @@ -25,35 +22,33 @@ requestBody: $ref: '#/components/requestBodies/common' responses: - '200': + "200": $ref: '#/components/responses/success' - '202': + "202": $ref: '#/components/responses/sent' - /rest/{kind}/{type}/{to}: post: summary: Even more RESTful mapping with certain components in the path. tags: - - generic + - generic security: - - basic: [] - - token: [] - - oauth2: [] + - basic: [] + - token: [] + - oauth2: [] parameters: - - $ref: '#/components/parameters/kind' - - $ref: '#/components/parameters/type' - - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/kind' + - $ref: '#/components/parameters/type' + - $ref: '#/components/parameters/to' requestBody: $ref: '#/components/requestBodies/common' responses: - '200': + "200": $ref: '#/components/responses/success' - /rest/echo: post: summary: Build as stanza and return it for inspection. tags: - - debug + - debug security: - basic: [] - token: [] @@ -61,22 +56,21 @@ requestBody: $ref: '#/components/requestBodies/common' responses: - '200': + "200": $ref: '#/components/responses/success' - /rest/ping/{to}: get: tags: - - query + - query summary: Ping a local or remote server or other entity security: - - basic: [] - - token: [] - - oauth2: [] + - basic: [] + - token: [] + - oauth2: [] parameters: - - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/to' responses: - '200': + "200": description: Test reachability of some address content: application/json: @@ -85,21 +79,19 @@ application/xmpp+xml: schema: $ref: '#/components/schemas/iq_pong' - - /rest/version/{to}: get: tags: - - query + - query summary: Ask what software version is used. security: - - basic: [] - - token: [] - - oauth2: [] + - basic: [] + - token: [] + - oauth2: [] parameters: - - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/to' responses: - '200': + "200": description: Version query response content: application/json: @@ -108,155 +100,146 @@ application/xmpp+xml: schema: $ref: '#/components/schemas/iq_result_version' - /rest/disco/{to}: get: tags: - - query + - query summary: Query a remote entity for supported features security: - - basic: [] - - token: [] - - oauth2: [] + - basic: [] + - token: [] + - oauth2: [] parameters: - - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/to' responses: - '200': + "200": $ref: '#/components/responses/success' - /rest/items/{to}: get: tags: - - query + - query summary: Query an entity for related services, chat rooms or other items security: - - basic: [] - - token: [] - - oauth2: [] + - basic: [] + - token: [] + - oauth2: [] parameters: - - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/to' responses: - '200': + "200": $ref: '#/components/responses/success' - /rest/extdisco/{to}: get: tags: - - query + - query summary: Query for external services (usually STUN and TURN) security: - - basic: [] - - token: [] - - oauth2: [] + - basic: [] + - token: [] + - oauth2: [] parameters: - - $ref: '#/components/parameters/to' - - name: type - in: query - schema: - type: string - example: stun + - $ref: '#/components/parameters/to' + - name: type + in: query + schema: + type: string + example: stun responses: - '200': + "200": $ref: '#/components/responses/success' - - /rest/archive/{to}: get: tags: - - query + - query summary: Query a message archive security: - - basic: [] - - token: [] - - oauth2: [] + - basic: [] + - token: [] + - oauth2: [] parameters: - - $ref: '#/components/parameters/to' - - name: with - in: query - schema: - type: string - - name: start - in: query - schema: - type: string - - name: end - in: query - schema: - type: string - - name: before-id - in: query - schema: - type: string - - name: after-id - in: query - schema: - type: string - - name: ids - in: query - schema: - type: string - description: comma-separated list of archive ids - - name: after - in: query - schema: - type: string - - name: before - in: query - schema: - type: string - - name: max - in: query - schema: - type: integer + - $ref: '#/components/parameters/to' + - name: with + in: query + schema: + type: string + - name: start + in: query + schema: + type: string + - name: end + in: query + schema: + type: string + - name: before-id + in: query + schema: + type: string + - name: after-id + in: query + schema: + type: string + - name: ids + in: query + schema: + type: string + description: comma-separated list of archive ids + - name: after + in: query + schema: + type: string + - name: before + in: query + schema: + type: string + - name: max + in: query + schema: + type: integer responses: - '200': + "200": $ref: '#/components/responses/success' - /rest/lastactivity/{to}: get: tags: - - query + - query summary: Query last activity of an entity. Sometimes used as "uptime" for servers. security: - - basic: [] - - token: [] - - oauth2: [] + - basic: [] + - token: [] + - oauth2: [] parameters: - - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/to' responses: - '200': + "200": $ref: '#/components/responses/success' - /rest/stats/{to}: get: tags: - - query + - query summary: Query an entity for statistics security: - - basic: [] - - token: [] - - oauth2: [] + - basic: [] + - token: [] + - oauth2: [] parameters: - - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/to' responses: - '200': + "200": $ref: '#/components/responses/success' - /rest/upload_request/{to}: get: tags: - - query + - query summary: Lorem ipsum security: - - basic: [] - - token: [] - - oauth2: [] + - basic: [] + - token: [] + - oauth2: [] parameters: - - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/to' responses: - '200': + "200": $ref: '#/components/responses/success' - components: schemas: stanza: @@ -271,7 +254,6 @@ - $ref: '#/components/schemas/message' - $ref: '#/components/schemas/presence' - $ref: '#/components/schemas/iq' - message: type: object xml: @@ -281,18 +263,17 @@ description: Which kind of stanza type: string enum: - - message + - message type: type: string enum: - - chat - - error - - groupchat - - headline - - normal + - chat + - error + - groupchat + - headline + - normal xml: attribute: true - to: $ref: '#/components/schemas/to' from: @@ -301,7 +282,6 @@ $ref: '#/components/schemas/id' lang: $ref: '#/components/schemas/lang' - body: $ref: '#/components/schemas/body' subject: @@ -310,7 +290,6 @@ $ref: '#/components/schemas/thread' invite: $ref: '#/components/schemas/invite' - state: $ref: '#/components/schemas/state' nick: @@ -319,7 +298,6 @@ $ref: '#/components/schemas/delay' replace: $ref: '#/components/schemas/replace' - html: $ref: '#/components/schemas/html' oob: @@ -344,19 +322,14 @@ $ref: '#/components/schemas/displayed' encryption: $ref: '#/components/schemas/encryption' - archive: $ref: '#/components/schemas/archive_result' - dataform: $ref: '#/components/schemas/dataform' - forwarded: $ref: '#/components/schemas/forwarded' - error: $ref: '#/components/schemas/error' - presence: type: object properties: @@ -364,7 +337,7 @@ description: Which kind of stanza type: string enum: - - presence + - presence type: type: string enum: @@ -385,14 +358,12 @@ $ref: '#/components/schemas/id' lang: $ref: '#/components/schemas/lang' - show: $ref: '#/components/schemas/show' status: $ref: '#/components/schemas/status' priority: $ref: '#/components/schemas/priority' - caps: $ref: '#/components/schemas/caps' nick: @@ -403,13 +374,10 @@ $ref: '#/components/schemas/vcard_update' idle_since: $ref: '#/components/schemas/idle_since' - muc: $ref: '#/components/schemas/muc' - error: $ref: '#/components/schemas/error' - iq: type: object properties: @@ -417,14 +385,14 @@ description: Which kind of stanza type: string enum: - - iq + - iq type: type: string enum: - - get - - set - - result - - error + - get + - set + - result + - error xml: attribute: true to: @@ -435,7 +403,6 @@ $ref: '#/components/schemas/id' lang: $ref: '#/components/schemas/lang' - ping: $ref: '#/components/schemas/ping' version: @@ -448,7 +415,6 @@ $ref: '#/components/schemas/items' command: $ref: '#/components/schemas/command' - stats: $ref: '#/components/schemas/stats' payload: @@ -463,10 +429,8 @@ $ref: '#/components/schemas/upload_request' upload_slot: $ref: '#/components/schemas/upload_slot' - error: $ref: '#/components/schemas/error' - iq_pong: description: Test reachability of some XMPP address type: object @@ -476,10 +440,9 @@ type: type: string enum: - - result + - result xml: attribute: true - iq_result_version: description: Version query response type: object @@ -489,60 +452,54 @@ type: type: string enum: - - result + - result xml: attribute: true version: $ref: '#/components/schemas/version' - kind: description: Which kind of stanza type: string enum: - - message - - presence - - iq - + - message + - presence + - iq type: description: Stanza type type: string enum: - - chat - - normal - - headline - - groupchat - - get - - set - - result - - available - - unavailable - - subscribe - - subscribed - - unsubscribe - - unsubscribed + - chat + - normal + - headline + - groupchat + - get + - set + - result + - available + - unavailable + - subscribe + - subscribed + - unsubscribe + - unsubscribed xml: attribute: true - to: description: recipient example: alice@example.com type: string xml: attribute: true - from: description: the sender example: bob@localhost.example type: string xml: attribute: true - id: description: Reasonably unique id. mod_rest generates one if left out. type: string xml: attribute: true - lang: description: Language code example: en @@ -550,17 +507,14 @@ prefix: xml attribute: true type: string - body: description: Human-readable chat message example: Hello, World! type: string - subject: description: Subject of message or group chat example: Talking about stuff type: string - thread: description: Message thread identifier properties: @@ -572,26 +526,22 @@ type: string xml: text: true - show: description: indicator of availability, ie away or not type: string enum: - - away - - chat - - dnd - - xa - + - away + - chat + - dnd + - xa status: description: Textual status message. type: string - priority: description: Presence priority type: integer maximum: 127 minimum: -128 - state: description: Chat state notifications, e.g. "is typing..." type: string @@ -599,30 +549,26 @@ namespace: http://jabber.org/protocol/chatstates x_name_is_value: true enum: - - active - - inactive - - gone - - composing - - paused + - active + - inactive + - gone + - composing + - paused example: composing - nick: type: string description: Nickname of the sender xml: name: nick namespace: http://jabber.org/protocol/nick - delay: type: string format: date-time - description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082 - format. + description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082 format. xml: name: delay namespace: urn:xmpp:delay x_single_attribute: stamp - replace: type: string description: ID of message being replaced (e.g. for corrections) @@ -630,7 +576,6 @@ name: replace namespace: urn:xmpp:message-correct:0 x_single_attribute: id - muc: description: Multi-User-Chat related type: object @@ -661,14 +606,12 @@ format: date-time xml: attribute: true - - invite: description: Invite to a group chat - title: "XEP-0249: Direct MUC Invitations" + title: 'XEP-0249: Direct MUC Invitations' type: object required: - - jid + - jid xml: name: x namespace: jabber:x:conference @@ -698,21 +641,18 @@ description: Whether the group chat continues a one-to-one chat xml: attribute: true - html: description: HTML version of 'body' example: <body><p>Hello!</p></body> type: string - ping: description: A ping. type: boolean enum: - - true + - true xml: name: ping namespace: urn:xmpp:ping - version: type: object description: Software version query @@ -727,116 +667,111 @@ type: string example: Linux required: - - name - - version + - name + - version xml: name: query namespace: jabber:iq:version - disco: description: Discover supported features oneOf: - - description: A full response - type: object - properties: - features: - description: List of URIs indicating supported features - type: array - items: + - description: A full response + type: object + properties: + features: + description: List of URIs indicating supported features + type: array + items: + type: string + identities: + description: List of abstract identities or types that describe the entity + type: array + example: + - name: Prosody + type: im + category: server + items: + type: object + properties: + name: + type: string + type: + type: string + category: + type: string + node: type: string - identities: - description: List of abstract identities or types that describe the - entity - type: array - example: - - name: Prosody - type: im - category: server - items: + extensions: type: object - properties: - name: - type: string - type: - type: string - category: - type: string - node: - type: string - extensions: - type: object - - description: A query with a node, or an empty response with a node - type: string - - description: Either a query, or an empty response - type: boolean - + - description: A query with a node, or an empty response with a node + type: string + - description: Either a query, or an empty response + type: boolean items: description: List of references to other entities oneOf: - - 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 - - type: string - description: A query with a node, or an empty reply list with a node - - description: An items query or empty list - type: boolean - enum: - - true - + - 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 + - type: string + description: A query with a node, or an empty reply list with a node + - description: An items query or empty list + type: boolean + enum: + - true command: description: Ad-hoc commands. oneOf: - - type: object - properties: - data: - $ref: '#/components/schemas/formdata' - action: - type: string - note: - type: object - properties: - text: - type: string - type: - type: string - enum: - - info - - warn - - error - form: - $ref: '#/components/schemas/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 - - type: string - description: Call a command by 'node' id, without arguments - + - type: object + properties: + data: + $ref: '#/components/schemas/formdata' + action: + type: string + note: + type: object + properties: + text: + type: string + type: + type: string + enum: + - info + - warn + - error + form: + $ref: '#/components/schemas/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 + - type: string + description: Call a command by 'node' id, without arguments oob: type: object description: Reference a media file @@ -852,7 +787,6 @@ desc: description: Optional description type: string - payload: title: 'XEP-0335: JSON Containers' description: A piece of arbitrary JSON with a type field attached @@ -870,7 +804,6 @@ datatype: example: urn:example:my-json#payload type: string - rsm: title: 'XEP-0059: Result Set Management' xml: @@ -892,7 +825,6 @@ type: string first: type: string - archive_query: title: 'XEP-0313: Message Archive Management' type: object @@ -908,7 +840,6 @@ xml: name: query namespace: urn:xmpp:mam:2 - archive_result: title: 'XEP-0313: Message Archive Management' xml: @@ -922,7 +853,6 @@ attribute: true forward: $ref: '#/components/schemas/forwarded' - forwarded: title: 'XEP-0297: Stanza Forwarding' xml: @@ -934,7 +864,6 @@ $ref: '#/components/schemas/message' delay: $ref: '#/components/schemas/delay' - dataform: description: Data form type: object @@ -952,10 +881,10 @@ value: description: Field value oneOf: - - type: string - - type: array - items: - type: string + - type: string + - type: array + items: + type: string type: description: Type of form field type: string @@ -974,23 +903,21 @@ type: type: string enum: - - form - - submit - - cancel - - result + - form + - submit + - cancel + - result instructions: type: string - formdata: description: Simplified data form carrying only values type: object additionalProperties: oneOf: - - type: string - - type: array - items: - type: string - + - type: string + - type: array + items: + type: string stats: description: Statistics type: array @@ -1013,7 +940,6 @@ type: string xml: attribute: true - lastactivity: type: object xml: @@ -1029,7 +955,6 @@ type: string xml: text: true - caps: type: object xml: @@ -1052,7 +977,6 @@ type: string xml: attribute: true - vcard_update: type: object xml: @@ -1062,7 +986,6 @@ photo: type: string example: adc83b19e793491b1c6ea0fd8b46cd9f32e592fc - reactions: type: object xml: @@ -1081,35 +1004,31 @@ xml: wrapped: false name: reactions - occupant_id: type: string xml: namespace: urn:xmpp:occupant-id:0 x_single_attribute: id name: occupant-id - attach_to: type: string xml: namespace: urn:xmpp:message-attaching:1 x_single_attribute: id name: attach-to - fallback: type: boolean xml: namespace: urn:xmpp:fallback:0 x_name_is_value: true name: fallback - stanza_ids: type: array items: type: object required: - - id - - by + - id + - by xml: namespace: urn:xmpp:sid:0 name: stanza-id @@ -1123,7 +1042,6 @@ attribute: true format: xmpp-jid type: string - reference: type: object xml: @@ -1149,9 +1067,8 @@ attribute: true type: string required: - - type - - uri - + - type + - uri reply: title: 'XEP-0461: Message Replies' description: Reference a message being replied to @@ -1168,20 +1085,17 @@ type: string xml: attribute: true - markable: type: boolean xml: namespace: urn:xmpp:chat-markers:0 x_name_is_value: true - displayed: type: string description: Message ID of a message that has been displayed xml: namespace: urn:xmpp:chat-markers:0 x_single_attribute: id - idle_since: type: string xml: @@ -1189,7 +1103,6 @@ x_single_attribute: since name: idle format: date-time - gateway: type: object xml: @@ -1202,7 +1115,6 @@ type: string jid: type: string - extdisco: type: object xml: @@ -1219,8 +1131,8 @@ xml: name: service required: - - type - - host + - type + - host properties: transport: xml: @@ -1260,7 +1172,6 @@ attribute: true type: string type: array - register: type: object description: Register with a service @@ -1313,9 +1224,8 @@ name: type: string required: - - username - - password - + - username + - password upload_slot: type: object xml: @@ -1335,17 +1245,17 @@ items: type: object required: - - name - - value + - name + - value xml: name: header properties: name: type: string enum: - - Authorization - - Cookie - - Expires + - Authorization + - Cookie + - Expires xml: attribute: true value: @@ -1363,8 +1273,8 @@ upload_request: type: object required: - - filename - - size + - filename + - size xml: name: request namespace: urn:xmpp:http:upload:0 @@ -1381,7 +1291,6 @@ type: integer xml: attribute: true - encryption: title: 'XEP-0380: Explicit Message Encryption' type: string @@ -1389,7 +1298,6 @@ x_single_attribute: namespace name: encryption namespace: urn:xmpp:eme:0 - error: description: Description of something gone wrong. See the Stanza Errors section in RFC 6120. type: object @@ -1398,11 +1306,11 @@ description: General category of error type: string enum: - - auth - - cancel - - continue - - modify - - wait + - auth + - cancel + - continue + - modify + - wait condition: description: Specific error condition. type: string @@ -1413,7 +1321,6 @@ text: description: Description of error intended for human eyes. type: string - securitySchemes: token: description: Tokens from mod_http_oauth2. @@ -1435,7 +1342,6 @@ prosody:user: Regular user privileges prosody:admin: Administrator privileges prosody:operator: Server operator privileges - requestBodies: common: required: true @@ -1449,7 +1355,6 @@ application/x-www-form-urlencoded: schema: description: A subset of the JSON schema, only top level string fields. - responses: success: description: The stanza was sent and returned a response. @@ -1471,9 +1376,7 @@ example: Hello type: string sent: - description: The stanza was sent without problem, and without response, - so an empty reply. - + description: The stanza was sent without problem, and without response, so an empty reply. parameters: to: name: to @@ -1493,5 +1396,3 @@ required: true schema: $ref: '#/components/schemas/type' - -...
