Add new OpenAPI 2.0 and 3.0 specifications, including comprehensive type definitions and example files. Update .gitignore and bunfig.toml, and remove obsolete MIGRATION.md. Enhance README with additional usage examples and clarify type definitions.

2025-12-09 20:47:44 +00:00 · 2025-09-25 14:57:24 +00:00
parent 3d0a7a3e3f
commit adc25abc0b
181 changed files with 30313 additions and 14953 deletions
--- a/3.2/webhooks.ts
+++ b/3.2/webhooks.ts
@@ -0,0 +1,130 @@
+import type { Extension } from "./extensions";
+import type { PathItemObject } from "./paths";
+import type { Reference } from "./references";
+
+/**
+ * -----
+ * Webhooks Object
+ * -----
+ *
+ * The incoming webhooks that MAY be received as part of this API and that the
+ * API consumer MAY choose to implement. Closely related to the `callbacks` feature,
+ * this section describes requests initiated other than by an API call, for example
+ * by an out of band registration.
+ *
+ * The key name is a unique string to refer to each webhook, while the (optionally
+ * referenced) Path Item Object describes a request that may be initiated by the
+ * API provider and the expected responses.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.2.0   | {@link https://spec.openapis.org/oas/v3.2.0#webhooks-object | OpenAPI 3.2.0 Webhooks Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @property `{webhookName}` - A unique string to refer to each webhook
+ * @property `PathItemObject` - The Path Item Object describing the webhook request
+ * @property `Reference` - A reference to a Path Item Object
+ * @property `x-${string}` - Specification Extensions
+ *
+ * @note
+ * Each webhook key must be a unique string identifier. The value can be either
+ * a Path Item Object or a Reference to a Path Item Object.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple webhook):
+ * ```ts
+ * const webhooks: Webhooks = {
+ *   "newPet": {
+ *     "post": {
+ *       "requestBody": {
+ *         "description": "Information about a new pet",
+ *         "content": {
+ *           "application/json": {
+ *             "schema": {
+ *               "$ref": "#/components/schemas/Pet"
+ *             }
+ *           }
+ *         }
+ *       },
+ *       "responses": {
+ *         "200": {
+ *           "description": "Webhook processed successfully"
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example (webhook with reference):
+ * ```ts
+ * const webhooks: Webhooks = {
+ *   "petUpdated": {
+ *     "$ref": "#/components/pathItems/PetUpdateWebhook"
+ *   }
+ * };
+ * ```
+ *
+ * @example (multiple webhooks):
+ * ```ts
+ * const webhooks: Webhooks = {
+ *   "newPet": {
+ *     "post": {
+ *       "summary": "New pet created",
+ *       "requestBody": {
+ *         "content": {
+ *           "application/json": {
+ *             "schema": { "$ref": "#/components/schemas/Pet" }
+ *           }
+ *         }
+ *       },
+ *       "responses": {
+ *         "200": { "description": "Success" }
+ *       }
+ *     }
+ *   },
+ *   "petDeleted": {
+ *     "delete": {
+ *       "summary": "Pet deleted",
+ *       "responses": {
+ *         "200": { "description": "Success" }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example (webhook with multiple operations):
+ * ```ts
+ * const webhooks: Webhooks = {
+ *   "petLifecycle": {
+ *     "post": {
+ *       "summary": "Pet created or updated",
+ *       "requestBody": {
+ *         "content": {
+ *           "application/json": {
+ *             "schema": { "$ref": "#/components/schemas/Pet" }
+ *           }
+ *         }
+ *       },
+ *       "responses": {
+ *         "200": { "description": "Success" }
+ *       }
+ *     },
+ *     "delete": {
+ *       "summary": "Pet deleted",
+ *       "responses": {
+ *         "200": { "description": "Success" }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export type Webhooks = Record<string, PathItemObject | Reference> & Extension;