Generate Webhooks (#62)

Author: cubahno

README.md

@@ -40,7 +40,7 @@ on the real value-add for your organization.
 
 ### Configuration & Filtering
 - **YAML-based configuration** with JSON schema validation
-- **Flexible filtering** - Include/exclude by paths, tags, operation IDs, schema properties, or extensions
+- **Flexible filtering** - Include/exclude by paths, tags, operation IDs, webhooks, schema properties, or extensions
 - **Transitive pruning** - Automatically remove schemas that are only referenced by filtered-out properties
 - **[OpenAPI Overlays](https://doordash-oss.github.io/oapi-codegen-dd/overlays/)** - Modify specs without editing originals (add extensions, remove paths)
 - **External file `$ref` resolution** - Split specs across multiple files with relative `$ref` references (auto-detected from spec path, or set `base-path` in config)
@@ -85,7 +85,8 @@ Tested against [2,137 real-world OpenAPI 3.0 specs](https://github.com/mockzilla
 | **Name Conflicts** | Manual fix required | Automatic resolution |
 | **Validation** | None | `Validate()` methods |
 | **Server Scaffold** | Interface only, manual boilerplate | Full typed solution (service, middleware, main.go) |
-| **Filtering** | Tags, operation IDs | + Paths, extensions, schema properties |
+| **Webhooks** | Not supported | Full type generation with filtering |
+| **Filtering** | Tags, operation IDs | + Paths, webhooks, extensions, schema properties |
 | **Overlays** | Single | Multiple, applied in order |
 | **Output** | Single file | Single or multiple files |
 | **Templates** | Monolithic | Composable with `{{define}}` blocks |

configuration-schema.json

@@ -139,11 +139,11 @@
       "properties": {
         "include": {
           "$ref": "#/definitions/FilterParamsConfig",
-          "description": "Paths, tags, operation IDs, and schema properties to include."
+          "description": "Paths, tags, operation IDs, webhooks, and schema properties to include."
         },
         "exclude": {
           "$ref": "#/definitions/FilterParamsConfig",
-          "description": "Paths, tags, operation IDs, and schema properties to exclude."
+          "description": "Paths, tags, operation IDs, webhooks, and schema properties to exclude."
         }
       },
       "required": []
@@ -173,6 +173,13 @@
           },
           "description": "List of operation IDs to include or exclude."
         },
+        "webhooks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of webhook names to include or exclude."
+        },
         "schema-properties": {
           "type": "object",
           "description": "Mapping of schema names to property names to include or exclude.",

docs/configuration.md

@@ -427,6 +427,25 @@ filter:
       - deleteUser
 ```
 
+### Filter by Webhooks
+
+Filter webhook entries by name. This is useful for OpenAPI 3.1 specs that define [webhooks](https://spec.openapis.org/oas/v3.1.0#fixed-fields) - 
+schemas referenced by included webhooks are preserved during pruning.
+
+```yaml
+filter:
+  include:
+    webhooks:
+      - order.created
+      - payment.completed
+  exclude:
+    webhooks:
+      - internal.debug
+```
+
+Webhook operations also respect tag and operation ID filters - if a webhook's operation doesn't match the tag/operation ID filter, 
+it will be removed just like path operations.
+
 ### Filter by Schema Properties
 
 Filter which properties are included in generated types. This triggers **transitive pruning** - schemas that are only referenced by filtered-out properties will also be pruned.

examples/webhooks/ex1/api.yaml

@@ -0,0 +1,140 @@
+openapi: 3.1.0
+info:
+  version: '1.0'
+  title: Webhook Events API
+  description: >
+    Example spec demonstrating webhook support.
+    Defines inbound webhook callbacks for payment and order events.
+webhooks:
+  payment.authorized:
+    post:
+      summary: Payment has been authorized
+      operationId: paymentAuthorized
+      tags:
+        - payments
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PaymentEvent'
+      responses:
+        '200':
+          description: Acknowledged
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WebhookAck'
+  order.shipped:
+    post:
+      summary: Order has been shipped
+      operationId: orderShipped
+      tags:
+        - orders
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderEvent'
+      responses:
+        '200':
+          description: Acknowledged
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WebhookAck'
+  inventory.low:
+    post:
+      summary: Inventory level is low
+      operationId: inventoryLow
+      tags:
+        - inventory
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - sku
+                - remaining
+              properties:
+                sku:
+                  type: string
+                remaining:
+                  type: integer
+      responses:
+        '200':
+          description: Acknowledged
+  internal.debug:
+    post:
+      summary: Internal debug event (excluded from generation)
+      operationId: internalDebug
+      tags:
+        - internal
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DebugEvent'
+      responses:
+        '200':
+          description: Acknowledged
+components:
+  schemas:
+    PaymentEvent:
+      type: object
+      required:
+        - id
+        - amount
+        - currency
+      properties:
+        id:
+          type: string
+          format: uuid
+        amount:
+          type: integer
+          description: Amount in minor units (e.g. cents)
+        currency:
+          type: string
+          minLength: 3
+          maxLength: 3
+        metadata:
+          $ref: '#/components/schemas/EventMetadata'
+    OrderEvent:
+      type: object
+      required:
+        - id
+        - trackingNumber
+      properties:
+        id:
+          type: string
+          format: uuid
+        trackingNumber:
+          type: string
+        carrier:
+          type: string
+        metadata:
+          $ref: '#/components/schemas/EventMetadata'
+    EventMetadata:
+      type: object
+      properties:
+        timestamp:
+          type: string
+          format: date-time
+        source:
+          type: string
+    WebhookAck:
+      type: object
+      properties:
+        received:
+          type: boolean
+    DebugEvent:
+      type: object
+      properties:
+        level:
+          type: string
+        message:
+          type: string

examples/webhooks/ex1/cfg.yaml

@@ -0,0 +1,8 @@
+# yaml-language-server: $schema=../../../configuration-schema.json
+package: gen
+output:
+  use-single-file: false
+filter:
+  exclude:
+    webhooks:
+      - internal.debug

examples/webhooks/ex1/gen/common.go

@@ -0,0 +1,3 @@
+package gen
+
+//go:generate go run github.com/doordash-oss/oapi-codegen-dd/v3/cmd/oapi-codegen -config cfg.yaml api.yaml