feat(asyncapi): add AsyncAPI plugin for event-driven API documentation

examples/asyncapi-sample/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "asyncapi-sample",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "zudoku dev",
+    "build": "zudoku build",
+    "preview": "zudoku preview"
+  },
+  "nx": {
+    "tags": [
+      "example"
+    ],
+    "targets": {
+      "build": {
+        "dependsOn": [
+          "zudoku:build"
+        ]
+      }
+    }
+  },
+  "devDependencies": {
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "zudoku": "workspace:*"
+  }
+}

examples/asyncapi-sample/zudoku.config.ts

@@ -0,0 +1,19 @@
+import type { ZudokuConfig } from "zudoku";
+
+const config: ZudokuConfig = {
+  site: {
+    title: "AsyncAPI Demo",
+  },
+  navigation: [{ label: "Event API", type: "link", to: "/async" }],
+  redirects: [{ from: "/", to: "/async" }],
+  asyncApis: {
+    type: "file",
+    input: "./multi-protocol.asyncapi.yaml",
+    path: "/async",
+    options: {
+      expandApiInformation: true,
+    },
+  },
+};
+
+export default config;

packages/zudoku/package.json

@@ -40,6 +40,7 @@
     "./plugins/api-keys": "./src/lib/plugins/api-keys/index.tsx",
     "./plugins/markdown": "./src/lib/plugins/markdown/index.tsx",
     "./plugins/openapi": "./src/lib/plugins/openapi/index.tsx",
+    "./plugins/asyncapi": "./src/lib/plugins/asyncapi/index.tsx",
     "./plugins/redirect": "./src/lib/plugins/redirect/index.tsx",
     "./plugins/custom-pages": "./src/lib/plugins/custom-pages/index.tsx",
     "./plugins/search-inkeep": "./src/lib/plugins/search-inkeep/index.tsx",
@@ -122,6 +123,10 @@
         "import": "./lib/zudoku.plugin-openapi.js",
         "types": "./dist/lib/plugins/openapi/index.d.ts"
       },
+      "./plugins/asyncapi": {
+        "import": "./lib/zudoku.plugin-asyncapi.js",
+        "types": "./dist/lib/plugins/asyncapi/index.d.ts"
+      },
       "./plugins/redirect": {
         "import": "./lib/zudoku.plugin-redirect.js",
         "types": "./dist/lib/plugins/redirect/index.d.ts"
@@ -204,6 +209,7 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "15.2.2",
+    "@asyncapi/parser": "^3.4.0",
     "@envelop/core": "5.3.2",
     "@graphql-typed-document-node/core": "3.2.0",
     "@lekoarts/rehype-meta-as-attributes": "3.0.3",

packages/zudoku/src/app/main.tsx

@@ -3,6 +3,7 @@ import {
   configuredApiCatalogPlugins,
   configuredApiPlugins,
 } from "virtual:zudoku-api-plugins";
+import { configuredAsyncApiPlugins } from "virtual:zudoku-asyncapi-plugins";
 import { configuredAuthProvider } from "virtual:zudoku-auth";
 import { configuredCustomPagesPlugin } from "virtual:zudoku-custom-pages-plugin";
 import { configuredDocsPlugin } from "virtual:zudoku-docs-plugin";
@@ -57,6 +58,7 @@ export const convertZudokuConfigToOptions = (
       ...(configuredAuthProvider ? [configuredAuthProvider] : []),
       ...(configuredDocsPlugin ? [configuredDocsPlugin] : []),
       ...configuredApiPlugins,
+      ...configuredAsyncApiPlugins,
       ...(configuredSearchPlugin ? [configuredSearchPlugin] : []),
       ...(configuredRedirectPlugin ? [configuredRedirectPlugin] : []),
       ...(configuredApiKeysPlugin ? [configuredApiKeysPlugin] : []),

packages/zudoku/src/config/validators/validate.ts

@@ -11,6 +11,10 @@ import type { ZudokuPlugin } from "../../lib/core/plugins.js";
 import type { ZudokuContext } from "../../lib/core/ZudokuContext.js";
 import type { FilterCatalogItemsFn } from "../../lib/plugins/api-catalog/index.js";
 import type { ApiConsumer } from "../../lib/plugins/api-keys/index.js";
+import type {
+  GenerateCodeSnippetFn as AsyncApiGenerateCodeSnippetFn,
+  TransformExamplesFn as AsyncApiTransformExamplesFn,
+} from "../../lib/plugins/asyncapi/interfaces.js";
 import type {
   GenerateCodeSnippetFn,
   TransformExamplesFn,
@@ -112,6 +116,60 @@ const ApiSchema = z.discriminatedUnion("type", [
   }),
 ]);
 
+// AsyncAPI Options Schema
+const AsyncApiOptionsSchema = z
+  .object({
+    defaultProtocol: z.string(),
+    supportedProtocols: z.array(
+      z.object({
+        value: z.string().min(1),
+        label: z.string().min(1),
+      }),
+    ),
+    disableSimulator: z.boolean(),
+    disableSidecar: z.boolean(),
+    showVersionSelect: z.enum(["always", "if-available", "hide"]),
+    expandAllTags: z.boolean(),
+    expandApiInformation: z.boolean(),
+    schemaDownload: z.object({ enabled: z.boolean() }).partial(),
+    transformExamples: z.custom<AsyncApiTransformExamplesFn>(
+      (val) => typeof val === "function",
+    ),
+    generateCodeSnippet: z.custom<AsyncApiGenerateCodeSnippetFn>(
+      (val) => typeof val === "function",
+    ),
+  })
+  .partial();
+
+const AsyncApiConfigSchema = z
+  .object({
+    server: z.string(),
+    path: z.string(),
+    options: AsyncApiOptionsSchema,
+  })
+  .partial();
+
+const AsyncApiSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("url"),
+    input: z.union([z.string(), z.array(VersionConfigSchema)]),
+    ...AsyncApiConfigSchema.shape,
+  }),
+  z.object({
+    type: z.literal("file"),
+    input: z.union([
+      z.string(),
+      z.array(z.union([z.string(), VersionConfigSchema])),
+    ]),
+    ...AsyncApiConfigSchema.shape,
+  }),
+  z.object({
+    type: z.literal("raw"),
+    input: z.string(),
+    ...AsyncApiConfigSchema.shape,
+  }),
+]);
+
 const ApiKeysSchema = z.object({
   enabled: z.boolean(),
   getConsumers: z
@@ -616,13 +674,15 @@ const BaseConfigSchema = z.object({
   search: SearchSchema,
   docs: DocsConfigSchema.optional(),
   apis: z.union([ApiSchema, z.array(ApiSchema)]),
+  asyncApis: z.union([AsyncApiSchema, z.array(AsyncApiSchema)]),
   catalogs: z.union([ApiCatalogSchema, z.array(ApiCatalogSchema)]),
   apiKeys: ApiKeysSchema,
   redirects: z.array(Redirect),
   sitemap: SiteMapSchema,
   enableStatusPages: z.boolean().optional(),
   defaults: z.object({
     apis: ApiOptionsSchema,
+    asyncApis: AsyncApiOptionsSchema,
     /**
      * @deprecated Use `apis.examplesLanguage` or `defaults.apis.examplesLanguage` instead
      */
@@ -635,6 +695,7 @@ const BaseConfigSchema = z.object({
 export const ZudokuConfig = BaseConfigSchema.partial();
 
 export type ZudokuApiConfig = z.infer<typeof ApiSchema>;
+export type ZudokuAsyncApiConfig = z.infer<typeof AsyncApiSchema>;
 export type VersionConfig = z.infer<typeof VersionConfigSchema>;
 export type ZudokuSiteMapConfig = z.infer<typeof SiteMapSchema>;
 export type ZudokuDocsConfig = z.infer<typeof DocsConfigSchema>;