Implement Webhooks

examples/digital-ocean-api.ts

@@ -640,6 +640,8 @@ export interface paths {
   };
 }
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: never;
   responses: never;
@@ -654,6 +656,7 @@ export interface external {
   "description.yml": {
 
     paths: Record<string, never>;
+    webhooks: Record<string, never>;
     components: Record<string, never>;
   }
   "resources/1-clicks/models/oneClicks_create.yml": {

examples/github-api.ts

@@ -7848,6 +7848,8 @@ export interface paths {
   };
 }
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     root: {

examples/octokit-ghes-3.6-diff-to-api.ts

@@ -1165,6 +1165,8 @@ export interface paths {
   };
 }
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     "global-hook": {

examples/stripe-api.ts

@@ -1993,6 +1993,8 @@ export interface paths {
   };
 }
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     /**

src/transform/index.ts

@@ -1,6 +1,7 @@
 import type { GlobalContext, OpenAPI3 } from "../types";
 import transformComponentsObject from "./components-object.js";
 import transformPathsObject from "./paths-object.js";
+import transformWebhooksObject from "./webhooks-object.js";
 
 /** transform top-level schema */
 export function transformSchema(schema: OpenAPI3, ctx: GlobalContext): Record<string, string> {
@@ -12,6 +13,10 @@ export function transformSchema(schema: OpenAPI3, ctx: GlobalContext): Record<st
   if (schema.paths) output.paths = transformPathsObject(schema.paths, ctx);
   else output.paths = "";
 
+  // webhooks
+  if (schema.webhooks) output.webhooks = transformWebhooksObject(schema.webhooks, ctx);
+  else output.webhooks = "";
+
   // components
   if (schema.components) output.components = transformComponentsObject(schema.components, ctx);
   else output.components = "";

src/transform/webhooks-object.ts

@@ -0,0 +1,23 @@
+import type { GlobalContext, WebhooksObject } from "../types";
+import { escStr, getEntries, indent } from "../utils.js";
+import transformPathItemObject from "./path-item-object.js";
+
+export default function transformWebhooksObject(webhooksObject: WebhooksObject, ctx: GlobalContext): string {
+  let { indentLv } = ctx;
+  const output: string[] = ["{"];
+  indentLv++;
+  for (const [name, pathItemObject] of getEntries(webhooksObject, ctx.alphabetize)) {
+    output.push(
+      indent(
+        `${escStr(name)}: ${transformPathItemObject(pathItemObject, {
+          path: `#/webhooks/${name}`,
+          ctx: { ...ctx, indentLv },
+        })};`,
+        indentLv
+      )
+    );
+  }
+  indentLv--;
+  output.push(indent("}", indentLv));
+  return output.join("\n");
+}

src/types.ts

@@ -138,6 +138,12 @@ export interface ComponentsObject extends Extensable {
  */
 export type PathsObject = { [pathname: string]: PathItemObject };
 
+/**
+ * [x.x.x] Webhooks Object
+ * Holds the webhooks definitions, indexed by their names. A webhook is defined by a Path Item Object; the only difference is that the request is initiated by the API provider.
+ */
+export type WebhooksObject = { [name: string]: PathItemObject };
+
 /**
  * [4.8.9] Path Item Object
  * Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.

test/index.test.ts

@@ -47,6 +47,8 @@ describe("openapiTS", () => {
       expect(generated).toBe(`${BOILERPLATE}
 export type paths = Record<string, never>;
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     Base: {
@@ -95,6 +97,8 @@ export type operations = Record<string, never>;
       expect(generated).toBe(`${BOILERPLATE}
 export type paths = Record<string, never>;
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     Example: {
@@ -163,6 +167,8 @@ export type operations = Record<string, never>;
       expect(generated).toBe(`${BOILERPLATE}
 export type paths = Record<string, never>;
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     Pet: {
@@ -222,6 +228,8 @@ export type operations = Record<string, never>;
       expect(generated).toBe(`${BOILERPLATE}
 export type paths = Record<string, never>;
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     ObjRef: {
@@ -265,6 +273,8 @@ export type operations = Record<string, never>;
         expect(generated).toBe(`${BOILERPLATE}
 export type paths = Record<string, never>;
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     User: {
@@ -305,6 +315,8 @@ export type operations = Record<string, never>;
         expect(generated).toBe(`${BOILERPLATE}
 export type paths = Record<string, never>;
 
+export type webhooks = Record<string, never>;
+
 export type components = {
   schemas: {
     User: {
@@ -350,6 +362,8 @@ export interface paths {
   };
 }
 
+export type webhooks = Record<string, never>;
+
 export type components = Record<string, never>;
 
 export type external = Record<string, never>;
@@ -371,6 +385,8 @@ export interface paths {
   };
 }
 
+export type webhooks = Record<string, never>;
+
 export type components = Record<string, never>;
 
 export type external = Record<string, never>;
@@ -400,6 +416,8 @@ export type operations = Record<string, never>;
         expect(generated).toBe(`${BOILERPLATE}
 export type paths = Record<string, never>;
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     /** Format: date-time */
@@ -430,6 +448,8 @@ export type operations = Record<string, never>;
 ${inject}
 export type paths = Record<string, never>;
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     /** Format: date-time */
@@ -477,6 +497,8 @@ export type operations = Record<string, never>;
         expect(generated).toBe(`${BOILERPLATE}${TYPE_HELPERS}
 export type paths = Record<string, never>;
 
+export type webhooks = Record<string, never>;
+
 export interface components {
   schemas: {
     User: OneOf<[{

test/webhooks-object.test.ts

@@ -0,0 +1,106 @@
+import type { GlobalContext, WebhooksObject } from "../src/types";
+import transformWebhooksObject from "../src/transform/webhooks-object.js";
+
+const options: GlobalContext = {
+  additionalProperties: false,
+  alphabetize: false,
+  defaultNonNullable: false,
+  discriminators: {},
+  immutableTypes: false,
+  indentLv: 0,
+  operations: {},
+  pathParamsAsTypes: false,
+  postTransform: undefined,
+  silent: true,
+  supportArrayLength: false,
+  transform: undefined,
+};
+
+describe("Webhooks Object", () => {
+  test("basic", () => {
+    const schema: WebhooksObject = {
+      "user-created": {
+        post: {
+          parameters: [
+            {
+              name: "signature",
+              in: "query",
+              schema: { type: "string" },
+              required: true,
+            },
+          ],
+          requestBody: {
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    id: { type: "string" },
+                    email: { type: "string" },
+                    name: { type: "string" },
+                  },
+                  required: ["id", "email"],
+                },
+              },
+            },
+          },
+          responses: {
+            200: {
+              description: "Return a 200 status to indicate that the data was received successfully",
+            },
+          },
+        },
+      },
+    };
+    const generated = transformWebhooksObject(schema, options);
+    expect(generated).toBe(`{
+  "user-created": {
+    post: {
+      parameters: {
+        query: {
+          signature: string;
+        };
+      };
+      requestBody?: {
+        content: {
+          "application/json": {
+            id: string;
+            email: string;
+            name?: string;
+          };
+        };
+      };
+      responses: {
+        /** @description Return a 200 status to indicate that the data was received successfully */
+        200: never;
+      };
+    };
+  };
+}`);
+  });
+
+  test("$ref", () => {
+    const schema: WebhooksObject = {
+      "user-created": {
+        parameters: [
+          { in: "query", name: "signature", schema: { type: "string" }, required: true },
+          { $ref: 'components["parameters"]["query"]["utm_source"]' },
+          { $ref: 'components["parameters"]["query"]["utm_email"]' },
+          { $ref: 'components["parameters"]["query"]["utm_campaign"]' },
+          { $ref: 'components["parameters"]["path"]["version"]' },
+        ],
+      },
+    };
+    const generated = transformWebhooksObject(schema, options);
+    expect(generated).toBe(`{
+  "user-created": {
+    parameters: {
+      query: {
+        signature: string;
+      } & (Pick<NonNullable<components["parameters"]["query"]>, "utm_source" | "utm_email" | "utm_campaign">);
+      path?: Pick<components["parameters"]["path"], "version">;
+    };
+  };
+}`);
+  });
+});