Add native zod schemas and documentation (#120)

* Add native zod schemas and documntation for 3 modules

* add more typing

* cache the documentation route more aggressively

* fix unit tests

* fix UI tests

* add zod-oai banner

* Revert "add zod-oai banner"

This reverts commit 2042270.

* add import

* add import to build file

* install zod-openapi dedicated in the package

* make zod-openapi external

* copy swagger assets

* disable tree shaking

* copy addl dir

* trigger deploy

* mark swagger as external in esbuild

* fix package.json

* try fixing build

* WORKING VERSION

* remove root-level registration

* allow caching docs UI route

* add tag descriptions

* try this new method of doing auth

* update packages

* fix unit tests

* fix live test path

* change build process

* fix build

Author: devksingh4

cloudformation/main.yml

@@ -736,6 +736,22 @@ Resources:
               - HEAD
             CachePolicyId: !Ref CloudfrontCachePolicy
             OriginRequestPolicyId: 216adef6-5c7f-47e4-b989-5492eafa07d3
+          - PathPattern: "/api/documentation*"
+            TargetOriginId: ApiGatewayOrigin
+            ViewerProtocolPolicy: redirect-to-https
+            AllowedMethods:
+              - GET
+              - HEAD
+              - OPTIONS
+              - PUT
+              - POST
+              - DELETE
+              - PATCH
+            CachedMethods:
+              - GET
+              - HEAD
+            CachePolicyId: "658327ea-f89d-4fab-a63d-7e88639e58f6"
+            OriginRequestPolicyId: 216adef6-5c7f-47e4-b989-5492eafa07d3
           - PathPattern: "/api/*"
             TargetOriginId: ApiGatewayOrigin
             ViewerProtocolPolicy: redirect-to-https

package.json

@@ -44,6 +44,7 @@
     "concurrently": "^9.1.2",
     "cross-env": "^7.0.3",
     "esbuild": "^0.23.0",
+    "esbuild-plugin-copy": "^2.1.1",
     "eslint": "^8.57.0",
     "eslint-config-airbnb": "^19.0.4",
     "eslint-config-airbnb-typescript": "^18.0.0",

src/api/build.js

@@ -1,5 +1,6 @@
 import esbuild from "esbuild";
 import { resolve } from "path";
+import { copy } from 'esbuild-plugin-copy'
 
 
 const commonParams = {
@@ -15,7 +16,7 @@ const commonParams = {
   target: "es2022", // Target ES2022
   sourcemap: false,
   platform: "node",
-  external: ["aws-sdk", "moment-timezone", "passkit-generator", "fastify"],
+  external: ["aws-sdk", "moment-timezone", "passkit-generator", "fastify", "zod", "zod-openapi", "@fastify/swagger", "@fastify/swagger-ui"],
   alias: {
     'moment-timezone': resolve(process.cwd(), '../../node_modules/moment-timezone/builds/moment-timezone-with-data-10-year-range.js')
   },
@@ -27,8 +28,26 @@ const commonParams = {
       const require = topLevelCreateRequire(import.meta.url);
       const __filename = fileURLToPath(import.meta.url);
       const __dirname = path.dirname(__filename);
+      import "zod-openapi/extend";
     `.trim(),
   }, // Banner for compatibility with CommonJS
+  plugins: [
+    copy({
+      resolveFrom: 'cwd',
+      assets: {
+        from: ['../../node_modules/@fastify/swagger-ui/static/*'],
+        to: ['../../dist/lambda/static'],
+      },
+    }),
+    copy({
+      resolveFrom: 'cwd',
+      assets: {
+        from: ['./public/*'],
+        to: ['../../dist/lambda/public'],
+      },
+    }),
+  ],
+  inject: [resolve(process.cwd(), "./zod-openapi-patch.js")],
 }
 esbuild
   .build({

src/api/components/index.ts

@@ -0,0 +1,39 @@
+import { AppRoles } from "common/roles.js";
+import { FastifyZodOpenApiSchema } from "fastify-zod-openapi";
+import { z } from "zod";
+
+export const ts = z.coerce
+  .number()
+  .min(0)
+  .optional()
+  .openapi({ description: "Staleness bound", example: 0 });
+export const groupId = z.string().min(1).openapi({
+  description: "Entra ID Group ID",
+  example: "d8cbb7c9-2f6d-4b7e-8ba6-b54f8892003b",
+});
+
+export function withTags<T extends FastifyZodOpenApiSchema>(
+  tags: string[],
+  schema: T,
+) {
+  return {
+    tags,
+    ...schema,
+  };
+}
+
+type RoleSchema = {
+  "x-required-roles": AppRoles[];
+  description: string;
+};
+
+export function withRoles<T extends FastifyZodOpenApiSchema>(
+  roles: AppRoles[],
+  schema: T,
+): T & RoleSchema {
+  return {
+    "x-required-roles": roles,
+    description: `Requires one of the following roles: ${roles.join(", ")}.${schema.description ? "\n\n" + schema.description : ""}`,
+    ...schema,
+  };
+}

src/api/esbuild.config.js

@@ -30,6 +30,7 @@ const buildOptions = {
       const require = topLevelCreateRequire(import.meta.url);
       const __filename = fileURLToPath(import.meta.url);
       const __dirname = path.dirname(__filename);
+      import "zod-openapi/extend";
     `.trim(),
   }, // Banner for compatibility with CommonJS
     plugins: [copyStaticFiles({

src/api/functions/auditLog.ts

@@ -2,14 +2,7 @@ import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
 import { marshall } from "@aws-sdk/util-dynamodb";
 import { genericConfig } from "common/config.js";
 import { Modules } from "common/modules.js";
-
-export type AuditLogEntry = {
-  module: Modules;
-  actor: string;
-  target: string;
-  requestId?: string;
-  message: string;
-};
+import { AuditLogEntry } from "common/types/logs.js";
 
 type AuditLogParams = {
   dynamoClient?: DynamoDBClient;

src/api/index.ts

@@ -1,4 +1,5 @@
 /* eslint import/no-nodejs-modules: ["error", {"allow": ["crypto"]}] */
+import "zod-openapi/extend";
 import { randomUUID } from "crypto";
 import fastify, { FastifyInstance } from "fastify";
 import FastifyAuthProvider from "@fastify/auth";
@@ -10,9 +11,9 @@ import { RunEnvironment, runEnvironments } from "../common/roles.js";
 import { InternalServerError } from "../common/errors/index.js";
 import eventsPlugin from "./routes/events.js";
 import cors from "@fastify/cors";
-import fastifyZodValidationPlugin from "./plugins/validate.js";
 import { environmentConfig, genericConfig } from "../common/config.js";
 import organizationsPlugin from "./routes/organizations.js";
+import authorizeFromSchemaPlugin from "./plugins/authorizeFromSchema.js";
 import icalPlugin from "./routes/ics.js";
 import vendingPlugin from "./routes/vending.js";
 import * as dotenv from "dotenv";
@@ -29,6 +30,17 @@ import membershipPlugin from "./routes/membership.js";
 import path from "path"; // eslint-disable-line import/no-nodejs-modules
 import roomRequestRoutes from "./routes/roomRequests.js";
 import logsPlugin from "./routes/logs.js";
+import fastifySwagger from "@fastify/swagger";
+import fastifySwaggerUI from "@fastify/swagger-ui";
+import {
+  fastifyZodOpenApiPlugin,
+  fastifyZodOpenApiTransform,
+  fastifyZodOpenApiTransformObject,
+  serializerCompiler,
+  validatorCompiler,
+} from "fastify-zod-openapi";
+import { ZodOpenApiVersion } from "zod-openapi";
+import { withTags } from "./components/index.js";
 
 dotenv.config();
 
@@ -81,10 +93,68 @@ async function init(prettyPrint: boolean = false) {
       return event.requestContext.requestId;
     },
   });
+  app.setValidatorCompiler(validatorCompiler);
+  app.setSerializerCompiler(serializerCompiler);
+  await app.register(authorizeFromSchemaPlugin);
   await app.register(fastifyAuthPlugin);
-  await app.register(fastifyZodValidationPlugin);
   await app.register(FastifyAuthProvider);
   await app.register(errorHandlerPlugin);
+  await app.register(fastifyZodOpenApiPlugin);
+  await app.register(fastifySwagger, {
+    openapi: {
+      info: {
+        title: "ACM @ UIUC Core API",
+        description: "ACM @ UIUC Core Management Platform",
+        version: "1.0.0",
+      },
+      servers: [
+        app.runEnvironment === "prod"
+          ? {
+              url: "https://core.acm.illinois.edu",
+              description: "Production API server",
+            }
+          : {
+              url: "https://core.aws.qa.acmuiuc.org",
+              description: "QA API server",
+            },
+      ],
+      tags: [
+        {
+          name: "Events",
+          description:
+            "Retrieve ACM @ UIUC-wide and organization-specific calendars and event metadata.",
+        },
+        {
+          name: "Generic",
+          description: "Retrieve metadata about a user or ACM @ UIUC .",
+        },
+        {
+          name: "iCalendar Integration",
+          description:
+            "Retrieve Events calendars in iCalendar format (for integration with external calendar clients).",
+        },
+        {
+          name: "IAM",
+          description: "Identity and Access Management for internal services.",
+        },
+        { name: "Linkry", description: "Link Shortener." },
+        {
+          name: "Logging",
+          description: "View audit logs for various services.",
+        },
+        {
+          name: "Membership",
+          description: "Purchasing or checking ACM @ UIUC membership.",
+        },
+      ],
+      openapi: "3.0.3" satisfies ZodOpenApiVersion, // If this is not specified, it will default to 3.1.0
+    },
+    transform: fastifyZodOpenApiTransform,
+    transformObject: fastifyZodOpenApiTransformObject,
+  });
+  await app.register(fastifySwaggerUI, {
+    routePrefix: "/api/documentation",
+  });
   await app.register(fastifyStatic, {
     root: path.join(__dirname, "public"),
     prefix: "/",
@@ -122,7 +192,11 @@ async function init(prettyPrint: boolean = false) {
     );
     done();
   });
-  app.get("/api/v1/healthz", (_, reply) => reply.send({ message: "UP" }));
+  app.get(
+    "/api/v1/healthz",
+    { schema: withTags(["Generic"], {}) },
+    (_, reply) => reply.send({ message: "UP" }),
+  );
   await app.register(
     async (api, _options) => {
       api.register(protectedRoute, { prefix: "/protected" });

src/api/lambda.ts

@@ -1,5 +1,6 @@
 /* eslint-disable */
 
+import "zod-openapi/extend";
 import awsLambdaFastify from "@fastify/aws-lambda";
 import init from "./index.js";
 

src/api/package.json

@@ -29,6 +29,8 @@
     "@fastify/caching": "^9.0.1",
     "@fastify/cors": "^10.0.1",
     "@fastify/static": "^8.1.1",
+    "@fastify/swagger": "^9.5.0",
+    "@fastify/swagger-ui": "^5.2.2",
     "@middy/core": "^6.0.0",
     "@middy/event-normalizer": "^6.0.0",
     "@middy/sqs-partial-batch-failure": "^6.0.0",
@@ -37,9 +39,10 @@
     "discord.js": "^14.15.3",
     "dotenv": "^16.4.5",
     "esbuild": "^0.24.2",
-    "fastify": "^5.1.0",
+    "fastify": "^5.3.2",
     "fastify-plugin": "^4.5.1",
     "fastify-raw-body": "^5.0.0",
+    "fastify-zod-openapi": "^4.1.1",
     "ical-generator": "^7.2.0",
     "jsonwebtoken": "^9.0.2",
     "jwks-rsa": "^3.1.0",
@@ -53,6 +56,7 @@
     "stripe": "^17.6.0",
     "uuid": "^11.0.5",
     "zod": "^3.23.8",
+    "zod-openapi": "^4.2.4",
     "zod-to-json-schema": "^3.23.2",
     "zod-validation-error": "^3.3.1"
   },

src/api/package.lambda.json

@@ -9,7 +9,11 @@
   "dependencies": {
     "moment-timezone": "^0.5.45",
     "passkit-generator": "^3.3.1",
-    "fastify": "^5.1.0"
+    "fastify": "^5.3.2",
+    "@fastify/swagger": "^9.5.0",
+    "@fastify/swagger-ui": "^5.2.2",
+    "zod": "^3.23.8",
+    "zod-openapi": "^4.2.4"
   },
   "devDependencies": {}
 }