Merge pull request #3577 from Infisical/feat/docs-support-openapi-titles

feat(docs): Support OpenAPI titles for Zod descriptions

backend/package-lock.json

@@ -122,7 +122,7 @@
         "tweetnacl-util": "^0.15.1",
         "uuid": "^9.0.1",
         "zod": "^3.22.4",
-        "zod-to-json-schema": "^3.22.4"
+        "zod-to-json-schema": "^3.24.5"
       },
       "bin": {
         "backend": "dist/main.js"
@@ -27442,11 +27442,12 @@
       }
     },
     "node_modules/zod-to-json-schema": {
-      "version": "3.22.4",
-      "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.22.4.tgz",
-      "integrity": "sha512-2Ed5dJ+n/O3cU383xSY28cuVi0BCQhF8nYqWU5paEpl7fVdqdAmiLdqLyfblbNdfOFwFfi/mqU4O1pwc60iBhQ==",
+      "version": "3.24.5",
+      "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.24.5.tgz",
+      "integrity": "sha512-/AuWwMP+YqiPbsJx5D6TfgRTc4kTLjsh5SOcd4bLsfUg2RcEXrFMJl1DGgdHy2aCfsIA/cr/1JM0xcB2GZji8g==",
+      "license": "ISC",
       "peerDependencies": {
-        "zod": "^3.22.4"
+        "zod": "^3.24.1"
       }
     }
   }

backend/package.json

@@ -241,6 +241,6 @@
     "tweetnacl-util": "^0.15.1",
     "uuid": "^9.0.1",
     "zod": "^3.22.4",
-    "zod-to-json-schema": "^3.22.4"
+    "zod-to-json-schema": "^3.24.5"
   }
 }

backend/src/server/plugins/fastify-zod.ts

@@ -5,7 +5,7 @@
 import type { FastifySchema, FastifySchemaCompiler, FastifyTypeProvider } from "fastify";
 import type { FastifySerializerCompiler } from "fastify/types/schema";
 import type { z, ZodAny, ZodTypeAny } from "zod";
-import { zodToJsonSchema } from "zod-to-json-schema";
+import { PostProcessCallback, zodToJsonSchema } from "zod-to-json-schema";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type FreeformRecord = Record<string, any>;
@@ -28,9 +28,25 @@ interface Schema extends FastifySchema {
   hide?: boolean;
 }
 
+// Credit: https://github.com/StefanTerdell/zod-to-json-schema
+const jsonDescription: PostProcessCallback = (jsonSchema, def) => {
+  if (def.description) {
+    try {
+      return {
+        ...jsonSchema,
+        description: undefined,
+        ...JSON.parse(def.description)
+      };
+    } catch {}
+  }
+
+  return jsonSchema;
+};
+
 const zodToJsonSchemaOptions = {
   target: "openApi3",
-  $refStrategy: "none"
+  $refStrategy: "none",
+  postProcess: jsonDescription
 } as const;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

docs/mint.json

@@ -327,7 +327,7 @@
             }
           ]
         },
-        "documentation/platform/token",        
+        "documentation/platform/token",
         "documentation/platform/mfa",
         "documentation/platform/github-org-sync"
       ]