Add new Swagger Doc for the pusher

2022-04-28 11:39:08 +02:00
parent 231facbae2
commit 53b084ea7f
15 changed files with 498 additions and 71 deletions
@@ -1,4 +1,5 @@
 import { z } from "zod";
+import {extendApi} from "@anatine/zod-openapi";

 /*
 * WARNING! The original file is in /messages/JsonMessages.
@@ -6,10 +7,11 @@ import { z } from "zod";
 */

 export const isAdminApiData = z.object({
-    userUuid: z.string(),
-    email: z.nullable(z.string()),
-    roomUrl: z.string(),
-    mapUrlStart: z.string(),
+    // @ts-ignore
+    userUuid: extendApi(z.string(), {example: '998ce839-3dea-4698-8b41-ebbdf7688ad9'}),
+    email: extendApi(z.nullable(z.string()), {description: 'The email of the current user.', example: 'example@workadventu.re'}),
+    roomUrl: extendApi(z.string(), {example: '/@/teamSlug/worldSlug/roomSlug'}),
+    mapUrlStart: extendApi(z.string(), {description: 'The full URL to the JSON map file', example: 'https://myuser.github.io/myrepo/map.json'}),
    messages: z.optional(z.array(z.unknown())),
 });

@@ -1,46 +1,69 @@
 import { z } from "zod";
+import {extendApi} from "@anatine/zod-openapi";

 /*
 * WARNING! The original file is in /messages/JsonMessages.
 * All other files are automatically copied from this file on container startup / build
 */

-export const isErrorApiErrorData = z.object({
+export const isErrorApiErrorData = extendApi(
    // @ts-ignore
-    type: z.literal("error"),
-    code: z.string(),
-    title: z.string(),
-    subtitle: z.string(),
-    details: z.string(),
-    image: z.string(),
-});
+    z.object({
+        type: z.literal("error"),
+        code: extendApi(z.string(), {description: 'The system code of an error, it must be in SCREAMING_SNAKE_CASE.', example: 'ROOM_NOT_FOUND'}),
+        title: extendApi(z.string(), {description: "Big title displayed on the error screen.", example: "ERROR"}),
+        subtitle: extendApi(z.string(), {description: "Subtitle displayed to let the user know what is the main subject of the error.", example: "The room was not found."}),
+        details: extendApi(z.string(), {description: "Some others details on what the user can do if he don't understand the error.", example: "If you would like more information, you can contact the administrator or us at example@workadventu.re."}),
+        image: extendApi(z.string(), {description: "The URL of the image displayed just under the logo in the error screen.", example: 'https://example.com/error.png'}),
+    }),
+    {
+        description: 'This is an error that can be returned by the API, its type must be equal to "error".\n If such an error is caught, an error screen will be displayed.',
+    }
+);

-export const isErrorApiRetryData = z.object({
-    type: z.literal("retry"),
-    code: z.string(),
-    title: z.string(),
-    subtitle: z.string(),
-    details: z.string(),
-    image: z.string(),
-    buttonTitle: z.optional(z.nullable(z.string())),
-    timeToRetry: z.number(),
-    canRetryManual: z.boolean(),
-});
+export const isErrorApiRetryData = extendApi(
+    z.object({
+        type: z.literal("retry"),
+        code: extendApi(z.string(), {description: 'The system code of an error, it must be in SCREAMING_SNAKE_CASE. \n It will not be displayed to the user.', example: 'WORLD_FULL'}),
+        title: extendApi(z.string(), {description: "Big title displayed on the error screen.", example: "ERROR"}),
+        subtitle: extendApi(z.string(), {description: "Subtitle displayed to let the user know what is the main subject of the error.", example: "Too successful, your WorkAdventure world is full!"}),
+        details: extendApi(z.string(), {description: "Some others details on what the user can do if he don't understand the error.", example: "New automatic attempt in 30 seconds"}),
+        image: extendApi(z.string(), {description: "The URL of the image displayed just under the logo in the waiting screen.", example: 'https://example.com/wait.png'}),
+        buttonTitle: extendApi(z.optional(z.nullable(z.string())), {description: "If this is not defined the button and the parameter canRetryManual is set to true, the button will be not displayed at all.", example: "Retry"}),
+        timeToRetry: extendApi(z.number(), {description: "This is the time (in millisecond) between the next auto refresh of the page.", example: 30_000}),
+        canRetryManual: extendApi(z.boolean(), {description: "This boolean show or hide the button to let the user refresh manually the current page.", example: true}),
+    }),
+    {
+        description: 'This is an error that can be returned by the API, its type must be equal to "retry".\n' +
+            'If such an error is caught, a waiting screen will be displayed.',
+    }
+);

-export const isErrorApiRedirectData = z.object({
-    type: z.literal("redirect"),
-    urlToRedirect: z.string(),
-});
+export const isErrorApiRedirectData = extendApi(
+    z.object({
+        type: z.literal("redirect"),
+        urlToRedirect: extendApi(z.string(), {description: 'A URL specified to redirect the user onto it directly', example: '/contact-us'}),
+    }),
+    {
+        description: 'This is an error that can be returned by the API, its type must be equal to "redirect".\n' +
+            'If such an error is caught, the user will be automatically redirected to urlToRedirect.',
+    }
+);

-export const isErrorApiUnauthorizedData = z.object({
-    type: z.literal("unauthorized"),
-    code: z.string(),
-    title: z.string(),
-    subtitle: z.string(),
-    details: z.string(),
-    image: z.string(),
-    buttonTitle: z.optional(z.nullable(z.string())),
-});
+export const isErrorApiUnauthorizedData = extendApi(
+    z.object({
+        type: z.literal("unauthorized"),
+        code: extendApi(z.string(), {description: "This is the system code of an error, it must be in SCREAMING_SNAKE_CASE.", example: "USER_ACCESS_FORBIDDEN"}),
+        title: extendApi(z.string(), {description: "Big title displayed on the error screen.", example: "ERROR"}),
+        subtitle: extendApi(z.string(), {description: "Subtitle displayed to let the user know what is the main subject of the error.", example: "You can't access this place."}),
+        details: extendApi(z.string(), {description: "Some others details on what the user can do if he don't understand the error.", example: "If you would like more information, you can contact the administrator or us at example@workadventu.re."}),
+        image: extendApi(z.string(), {description: "The URL of the image displayed just under the logo in the error screen.", example: 'https://example.com/error.png'}),
+        buttonTitle: extendApi(z.optional(z.nullable(z.string())), {description: "If this is not defined the button to logout will be not displayed.", example: "Log out"}),
+    }),
+    {
+        description: 'This is an error that can be returned by the API, its type must be equal to "unauthorized".\n' +
+            'If such an error is caught, an error screen will be displayed with a button to let him logout and go to login page.',
+    });

 export const isErrorApiData = z.discriminatedUnion("type", [
    isErrorApiErrorData,
@@ -1,4 +1,5 @@
 import { z } from "zod";
+import {extendApi} from "@anatine/zod-openapi";

 /*
 * WARNING! The original file is in /messages/JsonMessages.
@@ -6,20 +7,21 @@ import { z } from "zod";
 */

 export const isMapDetailsData = z.object({
-    mapUrl: z.string(),
-    authenticationMandatory: z.optional(z.nullable(z.boolean())),
-    group: z.nullable(z.string()),
+    // @ts-ignore
+    mapUrl: extendApi(z.string(), {description: 'The full URL to the JSON map file', example: 'https://myuser.github.io/myrepo/map.json'}),
+    authenticationMandatory: extendApi(z.optional(z.nullable(z.boolean())), {description: 'Whether the authentication is mandatory or not for this map', example: true}),
+    group: extendApi(z.nullable(z.string()), {description: 'The group this room is part of (maps the notion of "world" in WorkAdventure SAAS)', example: 'myorg/myworld'}),

-    contactPage: z.optional(z.nullable(z.string())),
-    iframeAuthentication: z.optional(z.nullable(z.string())),
+    contactPage: extendApi(z.optional(z.nullable(z.string())), {description: 'The URL to the contact page', example: 'https://mycompany.com/contact-us'}),
+    iframeAuthentication: extendApi(z.optional(z.nullable(z.string())), {description: 'The URL of the authentication Iframe', example: 'https://mycompany.com/authc'}),
    // The date (in ISO 8601 format) at which the room will expire
-    expireOn: z.optional(z.string()),
+    expireOn: extendApi(z.optional(z.string()), {description: 'The date (in ISO 8601 format) at which the room will expire', example: '2022-11-05T08:15:30-05:00'}),
    // Whether the "report" feature is enabled or not on this room
-    canReport: z.optional(z.boolean()),
+    canReport: extendApi(z.optional(z.boolean()), {description: 'Whether the "report" feature is enabled or not on this room', example: true}),
    // The URL of the logo image on the loading screen
-    loadingLogo: z.optional(z.nullable(z.string())),
+    loadingLogo: extendApi(z.optional(z.nullable(z.string())), {description: 'The URL of the image to be used on the loading page', example: 'https://example.com/logo.png'}),
    // The URL of the logo image on "LoginScene"
-    loginSceneLogo: z.optional(z.nullable(z.string())),
+    loginSceneLogo: extendApi(z.optional(z.nullable(z.string())), {description: 'The URL of the image to be used on the LoginScene', example: 'https://example.com/logo_login.png'}),
 });

 export type MapDetailsData = z.infer<typeof isMapDetailsData>;