Adding OpenAPI documentation for the pusher.

The pusher now exposes a "/openapi" endpoint and a "/swagger-ui/" endpoint.
2022-02-21 19:05:56 +01:00
parent 80761804a7
commit 3b4f06d659
10 changed files with 547 additions and 6 deletions
@@ -10,6 +10,94 @@ import { BaseHttpController } from "./BaseHttpController";
 export class MapController extends BaseHttpController {
    // Returns a map mapping map name to file name of the map
    routes() {
+        /**
+         * @openapi
+         * /map:
+         *   get:
+         *     description: Returns a map mapping map name to file name of the map
+         *     produces:
+         *      - "application/json"
+         *     parameters:
+         *      - name: "playUri"
+         *        in: "query"
+         *        description: "The full URL of WorkAdventure to load this map"
+         *        required: true
+         *        type: "string"
+         *      - name: "authToken"
+         *        in: "query"
+         *        description: "The authentication token"
+         *        required: true
+         *        type: "string"
+         *     responses:
+         *       200:
+         *         description: The details of the map
+         *         content:
+         *           application/json:
+         *             schema:
+         *               type: object
+         *               required:
+         *                 - mapUrl
+         *                 - policy_type
+         *                 - tags
+         *                 - textures
+         *                 - authenticationMandatory
+         *                 - roomSlug
+         *                 - contactPage
+         *                 - group
+         *               properties:
+         *                 mapUrl:
+         *                   type: string
+         *                   description: The full URL to the JSON map file
+         *                   example: https://myuser.github.io/myrepo/map.json
+         *                 policy_type:
+         *                   type: integer
+         *                   description: ANONYMOUS_POLICY = 1, MEMBERS_ONLY_POLICY = 2, USE_TAGS_POLICY= 3
+         *                   example: 1
+         *                 tags:
+         *                   type: array
+         *                   description: The list of tags required to enter this room
+         *                   items:
+         *                     type: string
+         *                     example: speaker
+         *                 textures:
+         *                   type: array
+         *                   description: The list of public textures for this map (TODO remove this)
+         *                   items:
+         *                     type: object
+         *                     properties:
+         *                       todo:
+         *                         type: string
+         *                 authenticationMandatory:
+         *                   type: boolean|null
+         *                   description: Whether the authentication is mandatory or not for this map.
+         *                   example: true
+         *                 roomSlug:
+         *                   type: string
+         *                   description: The slug of the room
+         *                   deprecated: true
+         *                   example: foo
+         *                 contactPage:
+         *                   type: string|null
+         *                   description: The URL to the contact page
+         *                   example: https://mycompany.com/contact-us
+         *                 group:
+         *                   type: string|null
+         *                   description: The group this room is part of (maps the notion of "world" in WorkAdventure SAAS)
+         *                   example: myorg/myworld
+         *                 iframeAuthentication:
+         *                   type: string|null
+         *                   description: The URL of the authentication Iframe
+         *                   example: https://mycompany.com/authc
+         *                 expireOn:
+         *                   type: string|undefined
+         *                   description: The date (in ISO 8601 format) at which the room will expire
+         *                   example: 2022-11-05T08:15:30-05:00
+         *                 canReport:
+         *                   type: boolean|undefined
+         *                   description: Whether the "report" feature is enabled or not on this room
+         *                   example: true
+         *
+         */
        this.app.get("/map", (req, res) => {
            const query = parse(req.path_query);
            if (typeof query.playUri !== "string") {