add docs

Author: devksingh4

src/api/components/index.ts

@@ -28,16 +28,6 @@ export const acmCoreOrganization = z
     examples: ["ACM", "Infrastructure Committee"],
   });
 
-export function withTags<T extends FastifyZodOpenApiSchema>(
-  tags: string[],
-  schema: T,
-) {
-  return {
-    tags,
-    ...schema,
-  };
-}
-
 export type RoleSchema = {
   "x-required-roles": AppRoles[];
   "x-disable-api-key-auth": boolean;
@@ -48,6 +38,60 @@ type RolesConfig = {
   disableApiKeyAuth: boolean;
 };
 
+export const notAuthenticatedError = z
+  .object({
+    name: z.literal("UnauthenticatedError"),
+    id: z.literal(102),
+    message: z.string().min(1),
+  })
+  .meta({
+    id: "notAuthenticatedError",
+    description: "Request not authenticated.",
+  });
+
+export const notFoundError = z
+  .object({
+    name: z.literal("NotFoundError"),
+    id: z.literal(103),
+    message: z.string().min(1),
+  })
+  .meta({
+    id: "notFoundError",
+    description: "Resource was not found.",
+    example: {
+      name: "NotFoundError",
+      id: 103,
+      message: "{url} is not a valid URL.",
+    },
+  });
+
+export const notAuthorizedError = z
+  .object({
+    name: z.literal("UnauthorizedError"),
+    id: z.literal(101),
+    message: z.string().min(1),
+  })
+  .meta({
+    id: "notAuthorizedError",
+    description: "Request not authorized (lacking permissions).",
+  });
+
+export const internalServerError = z
+  .object({
+    name: z.literal("InternalServerError"),
+    id: z.literal(100),
+    message: z
+      .string()
+      .min(1)
+      .default(
+        "An internal server error occurred. Please try again or contact support.",
+      ),
+  })
+  .meta({
+    id: "internalServerError",
+    description: "The server encountered an error processing the request.",
+  });
+
 export function withRoles<T extends FastifyZodOpenApiSchema>(
   roles: AppRoles[],
   schema: T,
@@ -57,6 +101,11 @@ export function withRoles<T extends FastifyZodOpenApiSchema>(
   if (!disableApiKeyAuth) {
     security.push({ apiKeyAuth: [] });
   }
+  const responses = {
+    401: notAuthorizedError,
+    403: notAuthenticatedError,
+    ...schema.response,
+  };
   return {
     security,
     "x-required-roles": roles,
@@ -66,5 +115,22 @@ export function withRoles<T extends FastifyZodOpenApiSchema>(
         ? `${disableApiKeyAuth ? "API key authentication is not permitted for this route.\n\n" : ""}Requires one of the following roles: ${roles.join(", ")}.${schema.description ? `\n\n${schema.description}` : ""}`
         : "Requires valid authentication but no specific role.",
     ...schema,
+    response: responses,
+  };
+}
+
+export function withTags<T extends FastifyZodOpenApiSchema>(
+  tags: string[],
+  schema: T,
+) {
+  const responses = {
+    200: z.object({}),
+    500: internalServerError,
+    ...schema.response,
+  };
+  return {
+    tags,
+    ...schema,
+    response: responses,
   };
 }

src/api/createLambdaPackage.js

@@ -15,6 +15,10 @@ export const packagesToTransfer = [
   "passkit-generator",
   "argon2",
   "ioredis",
+  "fastify-zod-openapi",
+  "@fastify/swagger",
+  "zod-openapi",
+  "zod",
 ];
 const filePath = `${getPath().dirname}/package.json`;
 const writeFilePath = `${getPath().dirname}/package.lambda.json`;

src/api/package.json

@@ -59,10 +59,10 @@
     "stripe": "^18.0.0",
     "uuid": "^11.1.0",
     "zod": "^3.25.73",
-    "zod-validation-error": "^3.3.1"
+    "zod-validation-error": "^3.3.1",
+    "@fastify/swagger": "^9.5.0"
   },
   "devDependencies": {
-    "@fastify/swagger": "^9.5.0",
     "@fastify/swagger-ui": "^5.2.2",
     "@tsconfig/node22": "^22.0.1",
     "@types/aws-lambda": "^8.10.149",

src/api/routes/events.ts

@@ -40,6 +40,7 @@ import {
 } from "fastify-zod-openapi";
 import {
   acmCoreOrganization,
+  notFoundError,
   ts,
   withRoles,
   withTags,
@@ -178,7 +179,16 @@ const eventsPlugin: FastifyPluginAsyncZodOpenApi = async (
             includeMetadata: zodIncludeMetadata,
           }),
           summary: "Retrieve calendar events with applied filters.",
-          // response: { 200: getEventsSchema },
+          response: {
+            200: {
+              content: {
+                "application/json": {
+                  schema: z.array(getEventSchema),
+                  description: "Event data matching specified filter.",
+                },
+              },
+            },
+          },
         }),
       },
       async (request, reply) => {
@@ -315,6 +325,17 @@ const eventsPlugin: FastifyPluginAsyncZodOpenApi = async (
               example: "6667e095-8b04-4877-b361-f636f459ba42",
             }),
           }),
+          response: {
+            201: {
+              description: "Event modified.",
+              content: {
+                "application/json": {
+                  schema: z.null(),
+                },
+              },
+            },
+            404: notFoundError,
+          },
           summary: "Modify a calendar event.",
         }),
       ) satisfies FastifyZodOpenApiSchema,
@@ -472,6 +493,17 @@ const eventsPlugin: FastifyPluginAsyncZodOpenApi = async (
         [AppRoles.EVENTS_MANAGER],
         withTags(["Events"], {
           body: postRequestSchema,
+          response: {
+            201: {
+              description:
+                "Event created. The 'Location' header specifies the URL of the created event.",
+              content: {
+                "application/json": {
+                  schema: z.null(),
+                },
+              },
+            },
+          },
           summary: "Create a calendar event.",
         }),
       ) satisfies FastifyZodOpenApiSchema,
@@ -583,12 +615,17 @@ const eventsPlugin: FastifyPluginAsyncZodOpenApi = async (
               example: "6667e095-8b04-4877-b361-f636f459ba42",
             }),
           }),
-          // response: {
-          //   201: z.object({
-          //     id: z.string(),
-          //     resource: z.string(),
-          //   }),
-          // },
+          response: {
+            204: {
+              description: "Event deleted.",
+              content: {
+                "application/json": {
+                  schema: z.null(),
+                },
+              },
+            },
+            404: notFoundError,
+          },
           summary: "Delete a calendar event.",
         }),
       ) satisfies FastifyZodOpenApiSchema,
@@ -689,8 +726,18 @@ const eventsPlugin: FastifyPluginAsyncZodOpenApi = async (
           ts,
           includeMetadata: zodIncludeMetadata,
         }),
+        response: {
+          200: {
+            description: "Event data.",
+            content: {
+              "application/json": {
+                schema: getEventSchema,
+              },
+            },
+          },
+          404: notFoundError,
+        },
         summary: "Retrieve a calendar event.",
-        // response: { 200: getEventSchema },
       }),
     },
     async (request, reply) => {

src/api/routes/organizations.ts

@@ -3,6 +3,7 @@ import { AllOrganizationList } from "@acm-uiuc/js-shared";
 import fastifyCaching from "@fastify/caching";
 import rateLimiter from "api/plugins/rateLimiter.js";
 import { withTags } from "api/components/index.js";
+import { z } from "zod/v4";
 
 const organizationsPlugin: FastifyPluginAsync = async (fastify, _options) => {
   fastify.register(fastifyCaching, {
@@ -20,6 +21,18 @@ const organizationsPlugin: FastifyPluginAsync = async (fastify, _options) => {
     {
       schema: withTags(["Generic"], {
         summary: "Get a list of ACM @ UIUC sub-organizations.",
+        response: {
+          200: {
+            description: "List of ACM @ UIUC sub-organizations.",
+            content: {
+              "application/json": {
+                schema: z
+                  .enum(AllOrganizationList)
+                  .default(JSON.stringify(AllOrganizationList)),
+              },
+            },
+          },
+        },
       }),
     },
     async (_request, reply) => {