📝 docs: add schema documentation to OAuth provider routes

src/modules/auth/controllers/getOauthProviders.controller.ts

@@ -9,8 +9,8 @@ export const getOauthProvidersController = (ctx: Context) => {
     return returnReadResponse(
       ctx.set,
       200,
-      "Getting all oauth available list",
+      "Successfully retrieved the list of oauth providers",
-      oauthProviderServices
+      oauthProviderServices,
     );
   } catch (error) {
     return mainErrorHandler(ctx.set, error);

src/modules/auth/index.ts

@@ -7,10 +7,12 @@ import { getOauthProvidersController } from "./controllers/getOauthProviders.con
 import { getCallbackProviderUrlController } from "./controllers/getCallbackProviderUrl.controller";
 import { tokenValidationController } from "./controllers/tokenValidation.controller";
 import { logoutController } from "./controllers/logout.controller";
+import { tokenValidationSchema } from "./schemas/tokenValidation.schema";
+import { getOauthProvidersSchema } from "./schemas/getOauthProviders.schema";
 
-export const authModule = new Elysia({ prefix: "/auth" })
+export const authModule = new Elysia({ prefix: "/auth", tags: ["Authentication"] })
-  .post("/token/validate", tokenValidationController)
+  .post("/token/validate", tokenValidationController, tokenValidationSchema)
-  .get("/providers", getOauthProvidersController)
+  .get("/providers", getOauthProvidersController, getOauthProvidersSchema)
   .get("/providers/:name/callback", getCallbackProviderUrlController)
   .get("/github", githubRequestController)
   .get("/github/callback", githubCallbackController)

src/modules/auth/schemas/getOauthProviders.schema.ts

@@ -0,0 +1,56 @@
+import { success } from "zod";
+import { AppRouteSchema } from "../../../helpers/types/AppRouteSchema";
+
+export const getOauthProvidersSchema = {
+  detail: {
+    summary: "Get all available oauth providers",
+    description:
+      "This endpoint returns a list of all available and active oauth providers that can be used for authentication.",
+    responses: {
+      200: {
+        description: "Successfully retrieved the list of oauth providers",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                success: {
+                  type: "boolean",
+                  example: true,
+                },
+                status: {
+                  type: "number",
+                  example: 200,
+                },
+                message: {
+                  type: "string",
+                  example: "Successfully retrieved the list of oauth providers",
+                },
+                data: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      name: {
+                        type: "string",
+                        example: "google",
+                      },
+                      icon: {
+                        type: "string",
+                        example: "logos:google-icon",
+                      },
+                      req_endpoint: {
+                        type: "string",
+                        example: "auth/google",
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+} satisfies AppRouteSchema;

src/modules/auth/schemas/tokenValidation.schema.ts

@@ -0,0 +1,108 @@
+import { t } from "elysia";
+import { AppRouteSchema } from "../../../helpers/types/AppRouteSchema";
+
+export const tokenValidationSchema = {
+  headers: t.Object({
+    cookie: t.String({ description: "Authentication token in cookie format, e.g., auth_token=your_jwt_token;" }),
+  }),
+  detail: {
+    summary: "Validate authentication JWT token",
+    description:
+      "Validates the provided authentication JWT token with checking its validity and expiration in redis cache, if not exists, it will be checked in the database. If the token is valid, it returns the user information associated with the token. if the token is invalid or expired, it returns an error message.",
+    responses: {
+      200: {
+        description: "Validation successful",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                id: { type: "string", description: "Session ID", default: "xxxx-xxxxx-xxxxx-xxxx" },
+                isAuthenticated: {
+                  type: "boolean",
+                  description: "Indicates if the token is valid and the user is authenticated",
+                  default: true,
+                },
+                validUntil: {
+                  type: "string",
+                  format: "date-time",
+                  description: "Expiration date and time of the token",
+                  default: "2024-12-31T23:59:59Z",
+                },
+                user: {
+                  type: "object",
+                  properties: {
+                    id: { type: "string", description: "User ID", default: "user-12345" },
+                    name: { type: "string", description: "User's full name", default: "Lena Nouzen" },
+                    email: {
+                      type: "string",
+                      format: "email",
+                      description: "User's email address",
+                      default: "lena@example.com",
+                    },
+                    username: { type: "string", description: "User's username", default: "vladilena" },
+                    avatar: {
+                      type: "string",
+                      format: "uri",
+                      description: "URL to the user's avatar image",
+                      default: "https://example.com/avatar.jpg",
+                    },
+                    birthDate: {
+                      type: "string",
+                      format: "date",
+                      description: "User's birth date, can be null if not provided",
+                      default: null,
+                    },
+                    bioProfile: {
+                      type: "string",
+                      description: "User's bio/profile description, can be null if not provided",
+                      default: null,
+                    },
+                    preference: {
+                      type: "object",
+                      properties: {
+                        id: { type: "string", description: "Preference ID", default: "pref-12345" },
+                        userId: { type: "string", description: "Associated User ID", default: "user-12345" },
+                        langPreference: {
+                          type: "string",
+                          description: "User's language preference, can be null if not provided",
+                          default: null,
+                        },
+                        adultFiltering: {
+                          type: "string",
+                          description: "User's adult content filtering setting",
+                          default: "strict",
+                        },
+                        adultAlert: {
+                          type: "string",
+                          description: "User's adult content alert setting",
+                          default: "enabled",
+                        },
+                        videoQuality: {
+                          type: "string",
+                          description: "User's preferred video quality setting",
+                          default: "1080p",
+                        },
+                        serviceDefaultId: {
+                          type: "string",
+                          description: "Default service ID for the user, can be null if not provided",
+                          default: null,
+                        },
+                        hideContries: {
+                          type: "array",
+                          items: { type: "string" },
+                          description: "List of country codes that the user has chosen to hide content from",
+                          default: ["US", "CN"],
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+} satisfies AppRouteSchema;