docs: document the services which jitsi meet can consume

* new documentation for the services which jitsi meet can consume for conference mapping to dial-in numbers

* attempted markdown link for swagger file from documentation file

doc/cloud-api.md

@@ -0,0 +1,5 @@
+# Jitsi Meet Cloud API
+
+The Jitsi Meet Cloud API is a specification for services which can support the integration of Jitsi Meet into other applications, for mapping conferences for dial-in support, and for supporting directory search and user invitations to conferences.
+
+The swagger for these services is provided in [cloud-api.swagger](cloud-api.swagger) in this same repository and directory.

doc/cloud-api.swagger

@@ -0,0 +1,147 @@
+swagger: "2.0"
+info:
+  description: "Documents the REST calls used by Jitsi Meet to integrate with other services"
+  version: "1.0.0"
+  title: "Swagger Video"
+  termsOfService: "https://jitsi.org/CloudAPITOS/"
+  contact:
+    email: "team@jitsi.org"
+host: "jitsi-api.jitsi.org"
+basePath: "/"
+tags:
+- name: "conferenceMapper"
+  description: "Conference to ID Mapper"
+  externalDocs:
+    description: "Conference API Details"
+    url: "https://jitsi.org/CloudAPI"
+- name: "phoneNumberList"
+  description: "List of dial-in numbers"
+schemes:
+  - "https"
+paths:
+  /conferenceMapper:
+    get:
+      tags:
+      - "conferenceMapper"
+      summary: "Create or retrieve conference ID mapping"
+      description: "When called with a conference, creates a new ID and both stores and returns the result.  When called with an ID, returns the mapping if previously created."
+      operationId: "GETconferenceMapper"
+      consumes:
+      - "application/json"
+      produces:
+      - "application/json"
+      parameters:
+      - in: "query"
+        name: "conference"
+        type: "string"
+        format: "JID"
+        description: "Full JID (room@conference.server.domain) for the conference to create or return existing conference mapping.  Used preferentially over all other input parameters (search by conference)"
+      - in: "query"
+        name: "id"
+        type: "number"
+        description: "ID to search for existing conference mapping.  Only used when provided alone (search by ID)"
+      responses:
+        200:
+          description: "mapping search performed"
+          schema:
+            $ref: "#/definitions/ConferenceMapperDetails"
+        405:
+          description: "Invalid input"
+    post:
+      tags:
+      - "conferenceMapper"
+      summary: "Create or retrieve conference ID mapping"
+      description: "When called with a conference, creates a new ID and both stores and returns the result.  When called with an ID, returns the mapping if previously created."
+      operationId: "POSTconferenceMapper"
+      consumes:
+      - "application/json"
+      produces:
+      - "application/json"
+      parameters:
+      - in: "body"
+        name: "body"
+        description: "Conference Mapper Request"
+        required: true
+        schema:
+          $ref: "#/definitions/ConferenceMapperRequest"
+      responses:
+        200:
+          description: "mapping search performed"
+          schema:
+            $ref: "#/definitions/ConferenceMapperDetails"
+        405:
+          description: "Invalid input"
+ 
+  /phoneNumberList:
+    get:
+      tags:
+      - "phoneNumberList"
+      summary: "Returns a list phone numbers by country"
+      description: "Used to populate the Share The Link section of jitsi-meet"
+      operationId: "phoneNumberList"
+      produces:
+      - "application/json"
+      responses:
+        200:
+          description: "successful operation"
+          schema:
+            $ref: "#/definitions/PhoneNumberList"
+securityDefinitions:
+  token:
+    type: "apiKey"
+    name: "token"
+    in: "query"
+  Bearer:
+    type: "apiKey"
+    name: "Authorization"
+    in: "header"
+definitions:
+ 
+  ConferenceMapperRequest:
+    description: "Request to create or find a conference mapping"
+    type: "object"
+    properties:
+      id:
+        type: "number"
+        description: "ID to search for existing conference mapping.  Only used when provided alone (search by ID)"
+      conference:
+        type: "string"
+        format: "JID"
+        description: "Full JID (room@conference.server.domain) for the conference to create or return existing conference mapping.  Used preferentially over all other input parameters (search by conference)"
+      room:
+        type: "string"
+        description: "Room part of the conference.  Required if 'conference' is not provided.  Used to generate a 'conference' value (search by conference)"
+      domain:
+        type: "string"
+        description: "Domain part of the conference.  Used if 'conference' is not provided.  Defaults to domain of the API endpoint.   Used to generate a 'conference' value (search by conference)"
+ 
+  ConferenceMapperDetails:
+    description: "Conference mapping between conference JID and numeric ID"
+    type: "object"
+    properties:
+      id:
+        type: "number"
+        description: "Unique ID mapped to conference"
+      conference:
+        type: "string"
+        format: "JID"
+        description: "Full JID for the conference OR boolean false if no conference was found (search by ID)"
+ 
+  PhoneNumberList:
+    type: "object"
+    properties:
+      numbersEnabled:
+        type: "boolean"
+        description: "Control flag for Jitsi Meet user interface.  Must be set to true for Jitsi Meet to display phone-in UI elements"
+      numbers:
+        type: "object"
+        description: "Keys are Country Names, each value is an array of phone numbers"
+        additionalProperties:
+          type: "array"
+          items:
+            type: "string"
+            format: "phone"
+ 
+externalDocs:
+  description: "Find out more about the Jitsi Cloud API"
+  url: "https://jitsi.org/CloudAPI"