use openapi refs for docs

Author: devksingh4

src/api/components/index.ts

@@ -1,17 +1,52 @@
 import { AppRoles } from "common/roles.js";
 import { FastifyZodOpenApiSchema } from "fastify-zod-openapi";
 import * as z from "zod/v4";
+import { validateNetId } from "api/functions/validation.js";
+import { CoreOrganizationList } from "@acm-uiuc/js-shared";
 
 export const ts = z.coerce.number().min(0).optional().meta({
   description:
     "Staleness bound as Unix epoch time (requires authentication to specify)",
   example: 1752248256,
+  id: "AcmStalenessBoundTimestamp",
 });
+
 export const groupId = z.string().min(1).meta({
   description: "Entra ID Group ID",
   example: "d8cbb7c9-2f6d-4b7e-8ba6-b54f8892003b",
+  id: "EntraGroupId",
 });
 
+export const illinoisNetId = z
+  .string()
+  .min(3, { message: "NetID must be at least 3 characters." })
+  .max(8, { message: "NetID cannot be more than 8 characters." })
+  .regex(/^[a-zA-Z]{2}[a-zA-Z-]*(?:[2-9]|[1-9][0-9]{1,2})?$/, {
+    message: "NetID is not valid!",
+  })
+  .meta({
+    description: "Valid Illinois NetID",
+    example: "rjjones",
+    id: "IllinoisNetId",
+  });
+
+export const acmCoreOrganization = z
+  .enum(CoreOrganizationList as [string, ...string[]])
+  .meta({
+    description: "ACM Organization",
+    id: "AcmOrganization",
+    examples: ["ACM", "Infrastructure Committee"],
+  });
+
+export const semesterId = z
+  .string()
+  .min(1)
+  .meta({
+    description: "Short semester slug for a given semester.",
+    id: "IllinoisSemesterId",
+    examples: ["sp25", "fa24"],
+  });
+
 export function withTags<T extends FastifyZodOpenApiSchema>(
   tags: string[],
   schema: T,

src/api/functions/validation.ts

@@ -1,7 +1,7 @@
 import * as z from "zod/v4";
 
 export function validateEmail(email: string): boolean {
-  const emailSchema = z.string().email();
+  const emailSchema = z.email();
   const result = emailSchema.safeParse(email);
   return result.success;
 }

src/api/index.ts

@@ -102,13 +102,7 @@ async function init(prettyPrint: boolean = false, initClients: boolean = true) {
   });
   app.setValidatorCompiler(validatorCompiler);
   app.setSerializerCompiler(serializerCompiler);
-  await app.register(authorizeFromSchemaPlugin);
-  await app.register(fastifyAuthPlugin);
-  await app.register(FastifyAuthProvider);
-  await app.register(evaluatePoliciesPlugin);
-  await app.register(errorHandlerPlugin);
-  await app.register(fastifyZodOpenApiPlugin);
-  await app.register(locationPlugin);
+
   if (!isRunningInLambda) {
     try {
       const fastifySwagger = import("@fastify/swagger");
@@ -224,7 +218,13 @@ async function init(prettyPrint: boolean = false, initClients: boolean = true) {
       app.log.warn("Fastify Swagger not created!");
     }
   }
-
+  await app.register(authorizeFromSchemaPlugin);
+  await app.register(fastifyAuthPlugin);
+  await app.register(FastifyAuthProvider);
+  await app.register(evaluatePoliciesPlugin);
+  await app.register(errorHandlerPlugin);
+  await app.register(fastifyZodOpenApiPlugin);
+  await app.register(locationPlugin);
   await app.register(fastifyStatic, {
     root: path.join(__dirname, "public"),
     prefix: "/",

src/api/routes/events.ts

@@ -1,7 +1,6 @@
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 import { AppRoles } from "../../common/roles.js";
 import * as z from "zod/v4";
-import { CoreOrganizationList } from "@acm-uiuc/js-shared";
 import {
   DeleteItemCommand,
   GetItemCommand,
@@ -39,7 +38,12 @@ import {
   FastifyZodOpenApiSchema,
   FastifyZodOpenApiTypeProvider,
 } from "fastify-zod-openapi";
-import { ts, withRoles, withTags } from "api/components/index.js";
+import {
+  acmCoreOrganization,
+  ts,
+  withRoles,
+  withTags,
+} from "api/components/index.js";
 import { metadataSchema } from "common/types/events.js";
 import { evaluateAllRequestPolicies } from "api/plugins/evaluatePolicies.js";
 
@@ -108,8 +112,9 @@ const baseSchema = z.object({
     description: "Google Maps link for easy navigation to the event location.",
     example: "https://maps.app.goo.gl/dwbBBBkfjkgj8gvA8",
   }),
-  host: z.enum(CoreOrganizationList as [string, ...string[]]),
+  host: acmCoreOrganization,
   featured: z.boolean().default(false).meta({
+    ref: "acmOrganizationList",
     description:
       "Whether or not the event should be shown on the ACM @ UIUC website home page (and added to Discord, as available).",
   }),
@@ -166,12 +171,9 @@ const eventsPlugin: FastifyPluginAsyncZodOpenApi = async (
               description:
                 "If true, only get events which are marked as featured.",
             }),
-            host: z
-              .enum(CoreOrganizationList as [string, ...string[]])
-              .optional()
-              .meta({
-                description: "Retrieve events only for a specific host.",
-              }),
+            host: z.optional(acmCoreOrganization).meta({
+              description: "Retrieve events only for this organization.",
+            }),
             ts,
             includeMetadata: zodIncludeMetadata,
           }),

src/api/routes/ics.ts

@@ -22,7 +22,7 @@ import {
   FastifyZodOpenApiSchema,
   FastifyZodOpenApiTypeProvider,
 } from "fastify-zod-openapi";
-import { withTags } from "api/components/index.js";
+import { acmCoreOrganization, withTags } from "api/components/index.js";
 import * as z from "zod/v4";
 
 const repeatingIcalMap: Record<EventRepeatOptions, ICalEventJSONRepeatingData> =
@@ -52,9 +52,9 @@ const icalPlugin: FastifyPluginAsync = async (fastify, _options) => {
     {
       schema: withTags(["iCalendar Integration"], {
         params: z.object({
-          host: z
-            .optional(z.enum(CoreOrganizationList as [string, ...string[]]))
-            .meta({ description: "Host to get calendar for." }),
+          host: z.optional(acmCoreOrganization).meta({
+            description: "Organization to retrieve calendar for",
+          }),
         }),
         summary:
           "Retrieve the calendar for ACM @ UIUC or a specific sub-organization.",

src/api/routes/membership.ts

@@ -5,7 +5,6 @@ import {
   setPaidMembershipInTable,
   MEMBER_CACHE_SECONDS,
 } from "api/functions/membership.js";
-import { validateNetId } from "api/functions/validation.js";
 import { FastifyPluginAsync } from "fastify";
 import {
   BaseError,
@@ -26,7 +25,7 @@ import { SendMessageCommand, SQSClient } from "@aws-sdk/client-sqs";
 import rawbody from "fastify-raw-body";
 import { FastifyZodOpenApiTypeProvider } from "fastify-zod-openapi";
 import * as z from "zod/v4";
-import { withTags } from "api/components/index.js";
+import { illinoisNetId, withTags } from "api/components/index.js";
 import { getKey, setKey } from "api/functions/redisCache.js";
 
 const membershipPlugin: FastifyPluginAsync = async (fastify, _options) => {
@@ -76,12 +75,7 @@ const membershipPlugin: FastifyPluginAsync = async (fastify, _options) => {
       "/checkout/:netId",
       {
         schema: withTags(["Membership"], {
-          params: z
-            .object({ netId: z.string().min(1) })
-            .refine((data) => validateNetId(data.netId), {
-              message: "NetID is not valid!",
-              path: ["netId"],
-            }),
+          params: z.object({ netId: illinoisNetId }),
           summary:
             "Create a checkout session to purchase an ACM @ UIUC membership.",
         }),
@@ -201,12 +195,7 @@ const membershipPlugin: FastifyPluginAsync = async (fastify, _options) => {
       "/:netId",
       {
         schema: withTags(["Membership"], {
-          params: z
-            .object({ netId: z.string().min(1) })
-            .refine((data) => validateNetId(data.netId), {
-              message: "NetID is not valid!",
-              path: ["netId"],
-            }),
+          params: z.object({ netId: illinoisNetId }),
           querystring: z.object({
             list: z.string().min(1).optional().meta({
               description:

src/api/routes/roomRequests.ts

@@ -25,7 +25,7 @@ import { genericConfig, notificationRecipients } from "common/config.js";
 import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
 import { AvailableSQSFunctions, SQSPayload } from "common/types/sqsMessage.js";
 import { SendMessageCommand, SQSClient } from "@aws-sdk/client-sqs";
-import { withRoles, withTags } from "api/components/index.js";
+import { semesterId, withRoles, withTags } from "api/components/index.js";
 import { FastifyZodOpenApiTypeProvider } from "fastify-zod-openapi";
 import * as z from "zod/v4";
 import { buildAuditLogTransactPut } from "api/functions/auditLog.js";
@@ -54,10 +54,7 @@ const roomRequestRoutes: FastifyPluginAsync = async (fastify, _options) => {
               description: "Room request ID.",
               example: "6667e095-8b04-4877-b361-f636f459ba42",
             }),
-            semesterId: z.string().min(1).meta({
-              description: "Short semester slug for a given semester.",
-              example: "sp25",
-            }),
+            semesterId,
           }),
           body: roomRequestStatusUpdateRequest,
         }),
@@ -185,10 +182,7 @@ const roomRequestRoutes: FastifyPluginAsync = async (fastify, _options) => {
         withTags(["Room Requests"], {
           summary: "Get room requests for a specific semester.",
           params: z.object({
-            semesterId: z.string().min(1).meta({
-              description: "Short semester slug for a given semester.",
-              example: "sp25",
-            }),
+            semesterId,
           }),
           querystring: z.object(
             getDefaultFilteringQuerystring({

src/common/types/iam.ts

@@ -30,13 +30,13 @@ export type InviteUserPostRequest = z.infer<typeof invitePostRequestSchema>;
 
 export const groupMappingCreatePostSchema = z.object({
   roles: z.union([
-  z.
-  array(z.nativeEnum(AppRoles)).
-  min(1).
-  refine((items) => new Set(items).size === items.length, {
-    message: "All roles must be unique, no duplicate values allowed"
-  }),
-  z.tuple([z.literal("all")])]
+    z.
+      array(z.nativeEnum(AppRoles)).
+      min(1).
+      refine((items) => new Set(items).size === items.length, {
+        message: "All roles must be unique, no duplicate values allowed"
+      }),
+    z.tuple([z.literal("all")])]
   )
 });
 
@@ -47,13 +47,13 @@ export type GroupMappingCreatePostRequest = z.infer<
 export const entraActionResponseSchema = z.object({
   success: z.array(z.object({ email: z.string() })).optional(),
   failure: z.
-  array(z.object({ email: z.string(), message: z.string() })).
-  optional()
+    array(z.object({ email: z.string(), message: z.string() })).
+    optional()
 });
 
 export type EntraActionResponse = z.infer<typeof entraActionResponseSchema>;
 
-export type GroupGetResponse = {id: string;displayName: string;}[];
+export type GroupGetResponse = { id: string; displayName: string; }[];
 
 export const groupModificationPatchSchema = z.object({
   add: z.array(z.string()),
@@ -79,7 +79,7 @@ export const entraProfilePatchRequest = z.object({
   displayName: z.string().min(1),
   givenName: z.string().min(1),
   surname: z.string().min(1),
-  mail: z.string().email()
+  mail: z.email()
 });
 
-export type ProfilePatchRequest = z.infer<typeof entraProfilePatchRequest>;
+export type ProfilePatchRequest = z.infer<typeof entraProfilePatchRequest>;

src/common/types/linkry.ts

@@ -13,24 +13,24 @@ export const getRequest = z.object({
 });
 
 export const linkrySlug = z.string().min(1).max(LINKRY_MAX_SLUG_LENGTH).meta({ description: "Linkry shortened URL path.", example: "shortened_url" });
-export const linkryAccessList = z.array(z.string()).meta({
+export const linkryAccessList = z.array(z.string().min(1)).meta({
   description: "List of groups to which access has been delegated.", example: ["c6a21a09-97c1-4f10-8ddd-fca11f967dc3", "88019d41-6c0b-4783-925c-3eb861a1ca0d"]
 });
 
 
 export const createRequest = z.object({
   slug: linkrySlug,
   access: linkryAccessList,
-  redirect: z.string().url().min(1).meta({ description: "Full URL to redirect to when the short URL is visited.", example: "https://google.com" })
+  redirect: z.url().min(1).meta({ description: "Full URL to redirect to when the short URL is visited.", example: "https://google.com" })
 });
 
 export const linkRecord = z.object({
   access: linkryAccessList,
   slug: linkrySlug,
-  createdAt: z.string().datetime(),
-  updatedAt: z.string().datetime(),
-  redirect: z.string().url(),
-  owner: z.string()
+  createdAt: z.iso.datetime(),
+  updatedAt: z.iso.datetime(),
+  redirect: z.url(),
+  owner: z.string().min(1)
 });
 
 export const delegatedLinkRecord = linkRecord.extend({
@@ -44,4 +44,4 @@ export type DelegatedLinkRecord = z.infer<typeof delegatedLinkRecord>;
 export const getLinksResponse = z.object({
   ownedLinks: z.array(linkRecord),
   delegatedLinks: z.array(linkRecord)
-});
+});