✨ feat: add openapi webhook docs

Author: m1212e

lib/helpers/sofaOpenAPIWebhookDocs.ts

@@ -0,0 +1,131 @@
+import type { useSofa } from "sofa-api";
+
+export const sofaOpenAPIWebhookDocs: Parameters<typeof useSofa>[0]["openAPI"] =
+	{
+		paths: {
+			"/webhook": {
+				post: {
+					operationId: "webhook_create",
+					description: "Creates a webhook subscription.",
+					tags: [],
+					parameters: [],
+					requestBody: {
+						content: {
+							"application/json": {
+								schema: {
+									$ref: "#/components/schemas/WebhookCreateBody",
+								},
+							},
+						},
+					},
+					responses: {
+						"200": {
+							content: {
+								"application/json": {
+									schema: {
+										$ref: "#/components/schemas/WebhookDetailResponse",
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+			"/webhook/{id}": {
+				post: {
+					operationId: "webhook_update",
+					description: "Updates a webhook subscription.",
+					parameters: [
+						{
+							name: "id",
+							in: "path",
+							description: "The ID of the webhook to update",
+							required: true,
+							schema: {
+								type: "string",
+							},
+						} as any,
+					],
+					requestBody: {
+						content: {
+							"application/json": {
+								schema: {
+									$ref: "#/components/schemas/WebhookCreateBody",
+								},
+							},
+						},
+					},
+					responses: {
+						"200": {
+							content: {
+								"application/json": {
+									schema: {
+										$ref: "#/components/schemas/WebhookDetailResponse",
+									},
+								},
+							},
+						},
+					},
+				},
+				delete: {
+					operationId: "webhook_delete",
+					description: "Removes a webhook subscription.",
+					tags: [],
+					parameters: [
+						{
+							name: "id",
+							in: "path",
+							description: "The ID of the webhook to delete",
+							required: true,
+							schema: {
+								type: "string",
+							},
+						} as any,
+					],
+					responses: {
+						"200": {
+							content: {
+								"application/json": {
+									schema: {
+										$ref: "#/components/schemas/WebhookDetailResponse",
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+		},
+		components: {
+			schemas: {
+				WebhookCreateBody: {
+					type: "object",
+					properties: {
+						subscription: {
+							description:
+								"The subscription to subscribe to. In many cases, these match the available query IDs without the '_query' suffix. E.g., 'findFirstUser_query' -> 'findFirstUser'. See the graphql schema for more details on what subscriptions are available.",
+							type: "string",
+						},
+						variables: {
+							description: "The variables to pass to the subscription.",
+							type: "object",
+						},
+						url: {
+							description: "The URL to send the webhook to.",
+							type: "string",
+						},
+					},
+				},
+				WebhookDetailResponse: {
+					type: "object",
+					properties: {
+						id: {
+							description:
+								"The ID of the webhook. Can be used as reference in update or delete calls.",
+							type: "string",
+						},
+					},
+				},
+			},
+		},
+	};

lib/rumble.ts

@@ -7,6 +7,7 @@ import { createAbilityBuilder } from "./abilityBuilder";
 import { createContextFunction } from "./context";
 import { createEnumImplementer } from "./enum";
 import { lazy } from "./helpers/lazy";
+import { sofaOpenAPIWebhookDocs } from "./helpers/sofaOpenAPIWebhookDocs";
 import { createObjectImplementer } from "./object";
 import { createPubSubInstance } from "./pubsub";
 import { createQueryImplementer } from "./query";
@@ -147,12 +148,19 @@ export const rumble = <
 
 	const createSofa = (
 		args: Omit<Parameters<typeof useSofa>[0], "schema" | "context">,
-	) =>
-		useSofa({
+	) => {
+		if (args.openAPI) {
+			args.openAPI = {
+				...sofaOpenAPIWebhookDocs,
+				...args.openAPI,
+			};
+		}
+		return useSofa({
 			...args,
 			schema: builtSchema(),
 			context,
 		});
+	};
 
 	return {
 		/**