view mod_rest/res/openapi.yaml @ 5536:96dec7681af8

mod_firewall: Update user marks to store instantly via map store The original approach was to keep marks in memory only, and persist them at shutdown. That saves I/O, at the cost of potentially losing marks on an unclean shutdown. This change persists marks instantly, which may have some performance overhead but should be more "correct". It also splits the marking/unmarking into an event which may be watched or even fired by other modules.
author Matthew Wild <mwild1@gmail.com>
date Thu, 08 Jun 2023 16:20:42 +0100
parents ce6e071d61a0
children 8bfcedd93a72
line wrap: on
line source

---
openapi: 3.0.1
info:
  title: mod_rest API
  version: 0.3.2
  description: |
    API for sending and receiving stanzas, in a REST-ish fashion or by
    responding to webhooks. Multiple formats supported, including native XML
    and a simplified JSON mapping.
  license:
    name: MIT
paths:
  /rest:
    post:
      summary: Send stanzas and receive responses. Webhooks work the same way.
      tags:
        - generic
      security:
        - basic: []
        - token: []
        - oauth2: []
      requestBody:
        $ref: '#/components/requestBodies/common'
      responses:
        "200":
          $ref: '#/components/responses/success'
        "202":
          $ref: '#/components/responses/sent'
  /rest/{kind}/{type}/{to}:
    post:
      summary: Even more RESTful mapping with certain components in the path.
      tags:
        - generic
      security:
        - basic: []
        - token: []
        - oauth2: []
      parameters:
        - $ref: '#/components/parameters/kind'
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/to'
      requestBody:
        $ref: '#/components/requestBodies/common'
      responses:
        "200":
          $ref: '#/components/responses/success'
  /rest/echo:
    post:
      summary: Build as stanza and return it for inspection.
      tags:
        - debug
      security:
        - basic: []
        - token: []
        - oauth2: []
      requestBody:
        $ref: '#/components/requestBodies/common'
      responses:
        "200":
          $ref: '#/components/responses/success'
  /rest/ping/{to}:
    get:
      tags:
        - query
      summary: Ping a local or remote server or other entity
      security:
        - basic: []
        - token: []
        - oauth2: []
      parameters:
        - $ref: '#/components/parameters/to'
      responses:
        "200":
          description: Test reachability of some address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/iq_pong'
            application/xmpp+xml:
              schema:
                $ref: '#/components/schemas/iq_pong'
  /rest/version/{to}:
    get:
      tags:
        - query
      summary: Ask what software version is used.
      security:
        - basic: []
        - token: []
        - oauth2: []
      parameters:
        - $ref: '#/components/parameters/to'
      responses:
        "200":
          description: Version query response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/iq_result_version'
            application/xmpp+xml:
              schema:
                $ref: '#/components/schemas/iq_result_version'
  /rest/disco/{to}:
    get:
      tags:
        - query
      summary: Query a remote entity for supported features
      security:
        - basic: []
        - token: []
        - oauth2: []
      parameters:
        - $ref: '#/components/parameters/to'
      responses:
        "200":
          $ref: '#/components/responses/success'
  /rest/items/{to}:
    get:
      tags:
        - query
      summary: Query an entity for related services, chat rooms or other items
      security:
        - basic: []
        - token: []
        - oauth2: []
      parameters:
        - $ref: '#/components/parameters/to'
      responses:
        "200":
          $ref: '#/components/responses/success'
  /rest/extdisco/{to}:
    get:
      tags:
        - query
      summary: Query for external services (usually STUN and TURN)
      security:
        - basic: []
        - token: []
        - oauth2: []
      parameters:
        - $ref: '#/components/parameters/to'
        - name: type
          in: query
          schema:
            type: string
            example: stun
      responses:
        "200":
          $ref: '#/components/responses/success'
  /rest/archive/{to}:
    get:
      tags:
        - query
      summary: Query a message archive
      security:
        - 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
      responses:
        "200":
          $ref: '#/components/responses/success'
  /rest/lastactivity/{to}:
    get:
      tags:
        - query
      summary: Query last activity of an entity. Sometimes used as "uptime" for servers.
      security:
        - basic: []
        - token: []
        - oauth2: []
      parameters:
        - $ref: '#/components/parameters/to'
      responses:
        "200":
          $ref: '#/components/responses/success'
  /rest/stats/{to}:
    get:
      tags:
        - query
      summary: Query an entity for statistics
      security:
        - basic: []
        - token: []
        - oauth2: []
      parameters:
        - $ref: '#/components/parameters/to'
      responses:
        "200":
          $ref: '#/components/responses/success'
  /rest/upload_request/{to}:
    get:
      tags:
        - query
      summary: Lorem ipsum
      security:
        - basic: []
        - token: []
        - oauth2: []
      parameters:
        - $ref: '#/components/parameters/to'
      responses:
        "200":
          $ref: '#/components/responses/success'
components:
  schemas:
    stanza:
      type: object
      example:
        body: Hello
        type: chat
        kind: message
        to: alice@example.com
        state: active
      oneOf:
        - $ref: '#/components/schemas/message'
        - $ref: '#/components/schemas/presence'
        - $ref: '#/components/schemas/iq'
    message:
      type: object
      xml:
        name: message
      properties:
        kind:
          description: Which kind of stanza
          type: string
          enum:
            - message
        type:
          type: string
          enum:
            - chat
            - error
            - groupchat
            - headline
            - normal
          xml:
            attribute: true
        to:
          $ref: '#/components/schemas/to'
        from:
          $ref: '#/components/schemas/from'
        id:
          $ref: '#/components/schemas/id'
        lang:
          $ref: '#/components/schemas/lang'
        body:
          $ref: '#/components/schemas/body'
        subject:
          $ref: '#/components/schemas/subject'
        thread:
          $ref: '#/components/schemas/thread'
        invite:
          $ref: '#/components/schemas/invite'
        state:
          $ref: '#/components/schemas/state'
        nick:
          $ref: '#/components/schemas/nick'
        delay:
          $ref: '#/components/schemas/delay'
        replace:
          $ref: '#/components/schemas/replace'
        html:
          $ref: '#/components/schemas/html'
        oob:
          $ref: '#/components/schemas/oob'
        reactions:
          $ref: '#/components/schemas/reactions'
        occupant_id:
          $ref: '#/components/schemas/occupant_id'
        attach_to:
          $ref: '#/components/schemas/attach_to'
        fallback:
          $ref: '#/components/schemas/fallback'
        stanza_ids:
          $ref: '#/components/schemas/stanza_ids'
        reference:
          $ref: '#/components/schemas/reference'
        reply:
          $ref: '#/components/schemas/reply'
        markable:
          $ref: '#/components/schemas/markable'
        displayed:
          $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:
        kind:
          description: Which kind of stanza
          type: string
          enum:
            - presence
        type:
          type: string
          enum:
            - available
            - unavailable
            - subscribe
            - subscribed
            - unsubscribe
            - unsubscribed
            - error
          xml:
            attribute: true
        to:
          $ref: '#/components/schemas/to'
        from:
          $ref: '#/components/schemas/from'
        id:
          $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:
          $ref: '#/components/schemas/nick'
        delay:
          $ref: '#/components/schemas/delay'
        vcard_update:
          $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:
        kind:
          description: Which kind of stanza
          type: string
          enum:
            - iq
        type:
          type: string
          enum:
            - get
            - set
            - result
            - error
          xml:
            attribute: true
        to:
          $ref: '#/components/schemas/to'
        from:
          $ref: '#/components/schemas/from'
        id:
          $ref: '#/components/schemas/id'
        lang:
          $ref: '#/components/schemas/lang'
        ping:
          $ref: '#/components/schemas/ping'
        version:
          $ref: '#/components/schemas/version'
        lastactivity:
          $ref: '#/components/schemas/lastactivity'
        disco:
          $ref: '#/components/schemas/disco'
        items:
          $ref: '#/components/schemas/items'
        command:
          $ref: '#/components/schemas/command'
        stats:
          $ref: '#/components/schemas/stats'
        payload:
          $ref: '#/components/schemas/payload'
        gateway:
          $ref: '#/components/schemas/gateway'
        register:
          $ref: '#/components/schemas/register'
        extdisco:
          $ref: '#/components/schemas/extdisco'
        upload_request:
          $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
      xml:
        name: iq
      properties:
        type:
          type: string
          enum:
            - result
          xml:
            attribute: true
    iq_result_version:
      description: Version query response
      type: object
      xml:
        name: iq
      properties:
        type:
          type: string
          enum:
            - result
          xml:
            attribute: true
        version:
          $ref: '#/components/schemas/version'
    kind:
      description: Which kind of stanza
      type: string
      enum:
        - message
        - presence
        - iq
    type:
      description: Stanza type
      type: string
      enum:
        - chat
        - normal
        - headline
        - groupchat
        - get
        - set
        - result
        - available
        - unavailable
        - subscribe
        - subscribed
        - unsubscribe
        - unsubscribed
      xml:
        attribute: true
    to:
      description: the intended recipient for the stanza
      example: alice@example.com
      format: xmpp-jid
      type: string
      xml:
        attribute: true
    from:
      description: the sender of the stanza
      example: bob@example.net
      format: xmpp-jid
      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
      xml:
        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:
        parent:
          type: string
          xml:
            attribute: true
        id:
          type: string
          xml:
            text: true
    show:
      description: indicator of availability, ie away or not
      type: string
      enum:
        - 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
      xml:
        namespace: http://jabber.org/protocol/chatstates
        x_name_is_value: true
      enum:
        - 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.
      title: 'XEP-0203: Delayed Delivery'
      xml:
        name: delay
        namespace: urn:xmpp:delay
        x_single_attribute: stamp
    replace:
      type: string
      description: ID of message being replaced (e.g. for corrections)
      xml:
        name: replace
        namespace: urn:xmpp:message-correct:0
        x_single_attribute: id
    muc:
      description: Multi-User-Chat related
      type: object
      xml:
        name: x
        namespace: http://jabber.org/protocol/muc
      properties:
        history:
          type: object
          properties:
            maxchars:
              type: integer
              minimum: 0
              xml:
                attribute: true
            maxstanzas:
              type: integer
              minimum: 0
              xml:
                attribute: true
            seconds:
              type: integer
              minimum: 0
              xml:
                attribute: true
            since:
              type: string
              format: date-time
              xml:
                attribute: true
    invite:
      description: Invite to a group chat
      title: 'XEP-0249: Direct MUC Invitations'
      type: object
      required:
        - jid
      xml:
        name: x
        namespace: jabber:x:conference
      properties:
        jid:
          type: string
          description: Address of the group chat
          format: xmpp-jid
          xml:
            attribute: true
        reason:
          type: string
          description: Optional message by the inviter
          xml:
            attribute: true
        password:
          type: string
          description: Password for the group chat, if required
          xml:
            attribute: true
        thread:
          type: string
          xml:
            attribute: true
        continue:
          type: boolean
          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
      xml:
        name: ping
        namespace: urn:xmpp:ping
    version:
      type: object
      description: Software version query
      properties:
        name:
          type: string
          example: My Software
        version:
          type: string
          example: 1.0.0
        os:
          type: string
          example: Linux
      required:
        - 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:
                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
            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
    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
    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
    oob:
      type: object
      description: Reference a media file
      xml:
        name: x
        namespace: jabber:x:oob
      properties:
        url:
          type: string
          description: URL of the attached media file
          example: https://media.example.net/thisfile.jpg
          format: uri
        desc:
          description: Optional description
          type: string
    payload:
      title: 'XEP-0335: JSON Containers'
      description: A piece of arbitrary JSON with a type field attached
      type: object
      xml:
        name: payload
        namespace: urn:xmpp:json-msg:0
      required:
        - datatype
        - data
      properties:
        data:
          example: '{"some":"json"}'
          type: object
        datatype:
          example: urn:example:my-json#payload
          type: string
    rsm:
      title: 'XEP-0059: Result Set Management'
      xml:
        name: set
        namespace: http://jabber.org/protocol/rsm
      type: object
      properties:
        last:
          type: string
        max:
          type: integer
        index:
          type: integer
        count:
          type: integer
        before:
          type: string
        after:
          type: string
        first:
          type: string
    archive_query:
      title: 'XEP-0313: Message Archive Management'
      type: object
      properties:
        queryid:
          xml:
            attribute: true
          type: string
        page:
          $ref: '#/components/schemas/rsm'
        form:
          $ref: '#/components/schemas/dataform'
      xml:
        name: query
        namespace: urn:xmpp:mam:2
    archive_result:
      title: 'XEP-0313: Message Archive Management'
      xml:
        namespace: urn:xmpp:mam:2
        name: result
      type: object
      properties:
        queryid:
          type: string
          xml:
            attribute: true
        forward:
          $ref: '#/components/schemas/forwarded'
    forwarded:
      title: 'XEP-0297: Stanza Forwarding'
      xml:
        name: forwarded
        namespace: urn:xmpp:forward:0
      type: object
      properties:
        message:
          $ref: '#/components/schemas/message'
        delay:
          $ref: '#/components/schemas/delay'
    dataform:
      description: Data form
      type: object
      properties:
        title:
          description: Title of the form
          example: TPS Report
          type: string
        fields:
          type: array
          items:
            description: Form field
            type: object
            properties:
              value:
                description: Field value
                oneOf:
                  - type: string
                  - type: array
                    items:
                      type: string
              type:
                description: Type of form field
                type: string
              label:
                description: Descriptive label for the field
                type: string
              desc:
                description: Longer description, i.e. that would go in a tooltip
                type: string
              required:
                description: Whether the field must be included in the form
                type: boolean
              var:
                description: Internal name of the field
                type: string
        type:
          type: string
          enum:
            - 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
    stats:
      description: Statistics
      type: array
      xml:
        name: query
        namespace: http://jabber.org/protocol/stats
        wrapped: true
      items:
        type: object
        properties:
          name:
            type: string
            xml:
              attribute: true
          unit:
            type: string
            xml:
              attribute: true
          value:
            type: string
            xml:
              attribute: true
    lastactivity:
      type: object
      xml:
        name: query
        namespace: jabber:iq:last
      properties:
        seconds:
          type: integer
          minimum: 0
          xml:
            attribute: true
        status:
          type: string
          xml:
            text: true
    caps:
      type: object
      xml:
        name: c
        namespace: http://jabber.org/protocol/caps
      properties:
        ver:
          type: string
          xml:
            attribute: true
        hash:
          type: string
          xml:
            attribute: true
        node:
          type: string
          xml:
            attribute: true
        ext:
          type: string
          xml:
            attribute: true
    vcard_update:
      type: object
      xml:
        name: x
        namespace: vcard-temp:x:update
      properties:
        photo:
          type: string
          example: adc83b19e793491b1c6ea0fd8b46cd9f32e592fc
    reactions:
      type: object
      xml:
        namespace: urn:xmpp:reactions:0
      properties:
        id:
          type: string
          xml:
            attribute: true
        reactions:
          type: array
          items:
            xml:
              name: reaction
            type: string
          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
        xml:
          namespace: urn:xmpp:sid:0
          name: stanza-id
        properties:
          id:
            xml:
              attribute: true
            type: string
          by:
            xml:
              attribute: true
            format: xmpp-jid
            type: string
    reference:
      type: object
      xml:
        namespace: urn:xmpp:reference:0
      properties:
        end:
          minimum: 0
          xml:
            attribute: true
          type: integer
        uri:
          xml:
            attribute: true
          format: uri
          type: string
        begin:
          minimum: 0
          xml:
            attribute: true
          type: integer
        type:
          xml:
            attribute: true
          type: string
      required:
        - type
        - uri
    reply:
      title: 'XEP-0461: Message Replies'
      description: Reference a message being replied to
      type: object
      xml:
        name: reply
        namespace: urn:xmpp:reply:0
      properties:
        to:
          type: string
          xml:
            attribute: true
        id:
          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:
        namespace: urn:xmpp:idle:1
        x_single_attribute: since
        name: idle
      format: date-time
    gateway:
      type: object
      xml:
        namespace: jabber:iq:gateway
        name: query
      properties:
        desc:
          type: string
        prompt:
          type: string
        jid:
          type: string
    extdisco:
      type: object
      xml:
        namespace: urn:xmpp:extdisco:2
        name: services
      properties:
        type:
          xml:
            attribute: true
          type: string
        services:
          items:
            type: object
            xml:
              name: service
            required:
              - type
              - host
            properties:
              transport:
                xml:
                  attribute: true
                type: string
              type:
                xml:
                  attribute: true
                type: string
              port:
                xml:
                  attribute: true
                type: integer
              host:
                xml:
                  attribute: true
                type: string
              expires:
                xml:
                  attribute: true
                format: datetime
                type: string
              username:
                xml:
                  attribute: true
                type: string
              password:
                xml:
                  attribute: true
                type: string
              restricted:
                xml:
                  attribute: true
                type: boolean
              name:
                xml:
                  attribute: true
                type: string
          type: array
    register:
      type: object
      description: Register with a service
      xml:
        namespace: jabber:iq:register
        name: query
      properties:
        nick:
          type: string
        misc:
          type: string
        password:
          type: string
        date:
          type: string
        address:
          type: string
        key:
          type: string
        text:
          type: string
        url:
          type: string
        zip:
          type: string
        phone:
          type: string
        last:
          type: string
        email:
          type: string
        remove:
          xml:
            x_name_is_value: true
          type: boolean
        city:
          type: string
        registered:
          xml:
            x_name_is_value: true
          type: boolean
        first:
          type: string
        state:
          type: string
        instructions:
          type: string
        username:
          type: string
        name:
          type: string
      required:
        - username
        - password
    upload_slot:
      type: object
      xml:
        name: slot
        namespace: urn:xmpp:http:upload:0
      properties:
        put:
          type: object
          properties:
            url:
              type: string
              format: uri
              xml:
                attribute: true
            headers:
              type: array
              items:
                type: object
                required:
                  - name
                  - value
                xml:
                  name: header
                properties:
                  name:
                    type: string
                    enum:
                      - Authorization
                      - Cookie
                      - Expires
                    xml:
                      attribute: true
                  value:
                    type: string
                    xml:
                      text: true
        get:
          type: object
          properties:
            url:
              type: string
              format: uri
              xml:
                attribute: true
    upload_request:
      type: object
      required:
        - filename
        - size
      xml:
        name: request
        namespace: urn:xmpp:http:upload:0
      properties:
        filename:
          type: string
          xml:
            attribute: true
        content-type:
          xml:
            attribute: true
            name: content-type
        size:
          type: integer
          xml:
            attribute: true
    encryption:
      title: 'XEP-0380: Explicit Message Encryption'
      type: string
      xml:
        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
      properties:
        type:
          description: General category of error
          type: string
          enum:
            - auth
            - cancel
            - continue
            - modify
            - wait
        condition:
          description: Specific error condition.
          type: string
          # enum: [ full list available in RFC 6120 ]
        code:
          description: Legacy numeric error code. Similar to HTTP status codes.
          type: integer
        text:
          description: Description of error intended for human eyes.
          type: string
  securitySchemes:
    token:
      description: Tokens from mod_http_oauth2.
      scheme: Bearer
      type: http
    basic:
      description: Use JID as username.
      scheme: Basic
      type: http
    oauth2:
      description: Needs mod_http_oauth2
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth2/authorize
          tokenUrl: https://example.com/oauth2/token
          scopes:
            prosody:restricted: Restricted account
            prosody:user: Regular user privileges
            prosody:admin: Administrator privileges
            prosody:operator: Server operator privileges
  requestBodies:
    common:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/stanza'
        application/xmpp+xml:
          schema:
            description: Single XMPP stanza in XML format.
        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.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/stanza'
        application/xmpp+xml:
          schema:
            description: Single XMPP stanza in XML format.
            example: <message><body>Hello</body></message>
        application/x-www-form-urlencoded:
          schema:
            description: A subset of the JSON schema, only top level string fields.
            example: body=Hello
        text/plain:
          schema:
            description: Plain text response used as message body.
            example: Hello
            type: string
    sent:
      description: The stanza was sent without problem, and without response, so an empty reply.
  parameters:
    to:
      name: to
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/to'
    kind:
      name: kind
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/kind'
    type:
      name: type
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/type'