feat: introduce basic open API specification (#78)

packages/types/src/aztec/utils.ts

@@ -42,7 +42,7 @@ export type StringifiedBuffer = {
 
 export const bufferSchema = z.preprocess(
   (val) => {
-    if ((val as StringifiedBuffer).data)
+    if (val && (val as StringifiedBuffer).data)
       return Buffer.from((val as StringifiedBuffer).data);
     return val;
   },

packages/types/src/general.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 
 export const hexStringSchema = z.custom<`0x${string}`>(
   (value) => {
-    return (value as string).startsWith("0x");
+    return typeof value === "string" && value.startsWith("0x");
   },
   { message: "Expected a hex string" }
 );

services/explorer-api/package.json

@@ -5,6 +5,7 @@
   "main": "index.js",
   "license": "UNLICENSED",
   "dependencies": {
+    "@anatine/zod-openapi": "2.2.6",
     "@aztec/aztec.js": "0.55.1",
     "@aztec/circuits.js": "0.55.1",
     "@aztec/protocol-contracts": "0.55.1",

services/explorer-api/src/environment.ts

@@ -1,5 +1,7 @@
 import { CHAIN_NAME } from "./constants.js";
 
+export const PUBLIC_API_KEY = process.env.PUBLIC_API_KEY ?? "d1e2083a-660c-4314-a6f2-1d42f4b944f4";
+
 export const PORT = Number(process.env.PORT) || 5000;
 export const BODY_LIMIT = process.env.BODY_LIMIT ?? "64kb";
 export const PARAMETER_LIMIT = Number(process.env.PARAMETER_LIMIT) || 100;

services/explorer-api/src/http-server/express-config.ts

@@ -1,10 +1,12 @@
 import bodyParser from "body-parser";
+import asyncHandler from "express-async-handler";
 import cors from "cors";
 import express from "express";
 import helmet from "helmet";
 import morgan from "morgan";
-import { init as initRoutes } from "./routes/index.js";
+import { init as initApiRoutes } from "./routes/index.js";
 import { createErrorMiddleware } from "@chicmoz-pkg/error-middleware";
+import { genereateOpenApiSpec } from "./open-api-spec.js";
 import { logger } from "../logger.js";
 
 type ExpressOptions = {
@@ -13,6 +15,14 @@ type ExpressOptions = {
   NODE_ENV: string;
 };
 
+const getHealthHandler = asyncHandler((_req, res) => {
+  // perhaps should be injected?
+  // TODO: evaluate actual health checks
+  //   - db
+  //   - message bus
+  res.sendStatus(200);
+});
+
 export function setup(
   app: express.Application,
   options: ExpressOptions
@@ -36,7 +46,12 @@ export function setup(
   app.use(morgan("common"));
 
   const router = express.Router();
-  initRoutes({ router });
+  router.get("/health", getHealthHandler);
+  const openApiSpec = genereateOpenApiSpec();
+  router.get("/open-api-specification", (_req, res) => {
+    res.json(openApiSpec);
+  });
+  initApiRoutes({ router });
   app.use(router);
 
   const errorMiddleware = createErrorMiddleware(logger);

services/explorer-api/src/http-server/index.ts

@@ -2,7 +2,7 @@ import express from "express";
 import http from "http";
 import { BODY_LIMIT, NODE_ENV, PARAMETER_LIMIT, PORT } from "../environment.js";
 import { logger } from "../logger.js";
-import {setup} from "./express-config.js";
+import { setup } from "./express-config.js";
 
 export const init = async () => {
   let resolveInit: () => void;

services/explorer-api/src/http-server/open-api-spec.ts

@@ -0,0 +1,34 @@
+import { PUBLIC_API_KEY } from "../environment.js";
+import { openApiPaths } from "./routes/index.js";
+
+export const genereateOpenApiSpec = () => ({
+  openapi: "3.1.0",
+  info: {
+    title: "Aztec Scan API",
+    version: "0.2.0",
+    description:
+      "API for exploring Aztec Network. Please note that this is a work in progress and the API is subject to change.",
+  },
+  servers: [
+    {
+      url: "https://api.chicmoz.info/v1/{apiKey}",
+      variables: {
+        apiKey: {
+          default: PUBLIC_API_KEY,
+          description: "The project ID",
+        },
+      },
+    },
+    {
+      url: "http://explorer-api.localhost/v1/{apiKey}",
+      variables: {
+        apiKey: {
+          default: PUBLIC_API_KEY,
+          description: "The project ID",
+        },
+      },
+    },
+  ],
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+  paths: openApiPaths,
+});