# HG changeset patch
# User Kim Alvefur <zash@zash.se>
# Date 1614815055 -3600
# Node ID 89571a20196ff36559c8bf6bc8fba9c02116060c
# Parent  9d576af186119410772119ed7503e3a56fcde40e
mod_rest/openapi: Describe 'version' endpoint in more detail

Use the limited xml "support" in openapi to show both forms of the
response.

diff -r 9d576af18611 -r 89571a20196f mod_rest/openapi.yaml
--- a/mod_rest/openapi.yaml	Thu Mar 04 00:43:26 2021 +0100
+++ b/mod_rest/openapi.yaml	Thu Mar 04 00:44:15 2021 +0100
@@ -6,7 +6,7 @@
     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.
-  version: 0.1.0
+  version: 0.2.0
   license:
     name: MIT
 paths:
@@ -77,7 +77,14 @@
       summary: Ask what software version is used.
       responses:
         200:
-          $ref: '#/components/responses/success'
+          description: Version query response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/iq_result_version'
+            application/xmpp+xml:
+              schema:
+                $ref: '#/components/schemas/iq_result_version'
       parameters:
       - $ref: '#/components/parameters/to'
 components:
@@ -125,7 +132,9 @@
         dataform:
           $ref: '#/components/schemas/dataform'
         version:
-          $ref: '#/components/schemas/version'
+          oneOf:
+            - $ref: '#/components/schemas/version'
+            - type: boolean
         payload:
           $ref: '#/components/schemas/payload'
         disco:
@@ -352,21 +361,41 @@
           - jid
           type: object
       description: List of references to other entities
+
+    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'
+
     version:
-      oneOf:
-      - type: boolean
-      - properties:
-          version:
-            type: string
-          name:
-            type: string
-          os:
-            type: string
-        required:
-        - name
-        - version
-        type: object
+      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
     payload:
       required:
         - datatype