mod_rest: Restructure API spec
To make referencing individual fields easier, apparently some things
don't like references to individual properties of an object.
--- 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.