diff mod_rest/openapi.yaml @ 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 949db0714b5f
children 8df6cc648963
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.