⚗️ experiment: try OpenAPI metadata configuration

src/helpers/types/AppRouteSchema.ts

@@ -0,0 +1,23 @@
+import { t, type RouteSchema } from "elysia";
+import type { OpenAPIV3 } from "openapi-types";
+
+export type AppRouteSchema = RouteSchema & {
+  detail?: Partial<{
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    externalDocs?: OpenAPIV3.ExternalDocumentationObject;
+    operationId?: string;
+    parameters?: (OpenAPIV3.ReferenceObject | OpenAPIV3.ParameterObject)[];
+    requestBody?: OpenAPIV3.ReferenceObject | OpenAPIV3.RequestBodyObject;
+    responses: OpenAPIV3.ResponsesObject;
+    callbacks?: {
+      [callback: string]:
+        | OpenAPIV3.ReferenceObject
+        | OpenAPIV3.CallbackObject;
+    };
+    deprecated?: boolean;
+    security?: OpenAPIV3.SecurityRequirementObject[];
+    servers?: OpenAPIV3.ServerObject[];
+  }>;
+};

src/index.ts

@@ -18,7 +18,19 @@ async function bootstrap() {
   new Elysia()
     .use(middleware)
     .use(routes)
-    .use(openapi())
+    .use(
+      openapi({
+        documentation: {
+          tags: [
+            {
+              name: "Internal",
+              description:
+                "Endpoints for internal use only, not exposed to public API consumers.",
+            },
+          ],
+        },
+      }),
+    )
     .listen(process.env.APP_PORT || 3000);
 
   console.log(

src/modules/internal/index.ts

@@ -1,4 +1,4 @@
-import Elysia from "elysia";
+import Elysia, { t } from "elysia";
 import { bulkInsertEpisodeController } from "./controllers/bulkInsertEpisode.controller";
 import { bulkInsertMediaController } from "./controllers/bulkInsertMedia.controller";
 import { createVideoServiceInternalController } from "./controllers/createVideoService.controller";
@@ -6,9 +6,13 @@ import { bulkInsertVideoController } from "./controllers/bulkInsertVideo.control
 import { updateAllEpisodeThumbnailController } from "./controllers/updateAllEpisodeThumbnail.controller";
 import { purgeUnusedSessionController } from "./controllers/purgeUnusedSession.controller";
 import { createHeroBannerController } from "./controllers/createHeroBanner.controller";
+import { bulkInsertMediaSchema } from "./schemas/bulkInsertMedia.schema";
 
-export const internalModule = new Elysia({ prefix: "/internal" })
-  .post("/media/bulk-insert", bulkInsertMediaController)
+export const internalModule = new Elysia({
+  prefix: "/internal",
+  tags: ["Internal"],
+})
+  .post("/media/bulk-insert", bulkInsertMediaController, bulkInsertMediaSchema)
   .post("/episode/bulk-insert", bulkInsertEpisodeController)
   .put("/episode/update-thumbnails", updateAllEpisodeThumbnailController)
   .post("/video/bulk-insert", bulkInsertVideoController)

src/modules/internal/schemas/bulkInsertMedia.schema.ts

@@ -0,0 +1,49 @@
+import { t } from "elysia";
+import { AppRouteSchema } from "../../../helpers/types/AppRouteSchema";
+
+export const bulkInsertMediaSchema = {
+  body: t.Object({
+    media_mal_id: t.Number({
+      description:
+        "The MyAnimeList ID of the media for which episodes will be inserted",
+    }),
+  }),
+  query: t.Object({
+    page: t.Optional(
+      t.Number({
+        description: "Episode page number to fetch",
+      }),
+    ),
+  }),
+  response: {
+    201: t.Object({
+      success: t.Boolean({ default: true }),
+      status: t.Number(),
+        message: t.String(),
+        data: t.Optional(
+            t.Unknown(), 
+        ),
+    }),
+    404: t.Object({
+        success: t.Boolean({ default: false }),
+        status: t.Number(),
+        message: t.String(),
+        error: t.Optional(
+          t.Unknown(),
+        ),
+      }),
+    500: t.Object({
+        success: t.Optional(t.Boolean({ default: false })),
+        status: t.Number(),
+        message: t.String(),
+        error: t.Optional(
+          t.Unknown(), 
+        ),
+      }),
+  },
+  detail: {
+    summary: "Bulk insert media",
+    description:
+      "Fetch media data from external sources and insert them into database",
+  },
+} satisfies AppRouteSchema;