Add support for webhooks in --openapi-scopes (#2481)

HNygard · pre-commit-ci[bot] · HNygardStb · web-flow · commit 61ae0da08dc8 · 2025-11-30T16:05:58.000+09:00
* Add support for `webhooks` in `--openapi-scopes` This PR adds support for the `webhooks` scope in the `--openapi-scopes` CLI option to handle OpenAPI Documents that have a `webhooks` root element instead of or in addition to `paths` and `components`. ## Background According to the [OpenAPI 3.1 specification](https://spec.openapis.org/oas/latest.html#oasWebhooks), OpenAPI documents can contain a `webhooks` root element that describes incoming webhooks. These webhooks have a similar structure to paths - they contain operations with `requestBody` that have content `schema` attributes, making them suitable for model generation. ## Changes Made ### 1. Added `Webhooks` to OpenAPIScope enum ```python class OpenAPIScope(Enum): Schemas = "schemas" Paths = "paths" Tags = "tags" Parameters = "parameters" Webhooks = "webhooks" # NEW ``` ### 2. Implemented webhooks processing in OpenAPI parser Added logic in the `parse_raw()` method to process webhooks similar to how paths are processed: ```python if OpenAPIScope.Webhooks in self.open_api_scopes: webhooks: dict[str, dict[str, Any]] = specification.get("webhooks", {}) webhooks_path = [*path_parts, "#/webhooks"] for webhook_name, methods_ in webhooks.items(): # Process each webhook operation for operation_name, raw_operation in methods.items(): if operation_name not in OPERATION_NAMES: continue self.parse_operation(raw_operation, [*path, operation_name]) ``` ### 3. Added comprehensive test coverage - Created `tests/data/openapi/webhooks.yaml` with a complete OpenAPI spec containing webhooks using dotted naming convention (`pet.new`, `pet.updated`) - Added test functions to validate webhooks-only and combined scope processing - Created expected output files for test validation ## Usage Examples ```bash # Generate models from webhooks only datamodel-codegen --input spec.yaml --openapi-scopes webhooks # Generate models from schemas and webhooks datamodel-codegen --input spec.yaml --openapi-scopes schemas webhooks # Generate models from all scopes including webhooks datamodel-codegen --input spec.yaml --openapi-scopes schemas paths tags parameters webhooks ``` ## Benefits - ✅ Support for OpenAPI 3.1+ webhooks specification - ✅ Generate Pydantic models for webhook request bodies - ✅ Reuse existing component schemas in webhook definitions - ✅ Flexible scope combinations (webhooks can be used alone or with other scopes) - ✅ Same robust processing as paths (handles references, nested objects, validation, etc.) - ✅ Supports dotted webhook naming convention (e.g., `pet.new`, `user.updated`) - ✅ Backward compatible - no breaking changes to existing functionality The implementation reuses the existing operation processing logic since webhooks have the same structure as path operations, ensuring consistency and reliability. Change made with Github Copilot. Verified locally on own data in addition to the tests created. Fixes #2059 * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Ignore PLR0912 * Removed PetNewPostRequest and PetUpdatedPostRequest classes. * Add test coverage * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Readme * Refactor test assertion to use assert_output for better readability * Add tests for OpenAPI generation with non-operation fields and webhooks * Enhance OpenAPI generation to support webhook-level parameters * Add support for X-Correlation-Id in pet.updated webhook parameters --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Hallvard Nygård <70267909+HNygardStb@users.noreply.github.com> Co-authored-by: Koudai Aono <koxudaxi@gmail.com>
diff --git a/README.md b/README.md
@@ -512,7 +512,7 @@ OpenAPI-only options:
   --include-path-parameters
                         Include path parameters in generated parameter models in addition to
                         query parameters (Only OpenAPI)
-  --openapi-scopes {schemas,paths,tags,parameters} [{schemas,paths,tags,parameters} ...]
+  --openapi-scopes {schemas,paths,tags,parameters,webhooks} [{schemas,paths,tags,parameters,webhooks} ...]
                         Scopes of OpenAPI model generation (default: schemas)
   --strict-nullable     Treat default field as a non-nullable field (Only OpenAPI)
   --use-operation-id-as-name
diff --git a/docs/index.md b/docs/index.md
@@ -504,7 +504,7 @@ OpenAPI-only options:
   --include-path-parameters
                         Include path parameters in generated parameter models in addition to
                         query parameters (Only OpenAPI)
-  --openapi-scopes {schemas,paths,tags,parameters} [{schemas,paths,tags,parameters} ...]
+  --openapi-scopes {schemas,paths,tags,parameters,webhooks} [{schemas,paths,tags,parameters,webhooks} ...]
                         Scopes of OpenAPI model generation (default: schemas)
   --strict-nullable     Treat default field as a non-nullable field (Only OpenAPI)
   --use-operation-id-as-name
diff --git a/src/datamodel_code_generator/__init__.py b/src/datamodel_code_generator/__init__.py
@@ -215,6 +215,7 @@ class OpenAPIScope(Enum):
     Paths = "paths"
     Tags = "tags"
     Parameters = "parameters"
+    Webhooks = "webhooks"
 
 
 class GraphQLScope(Enum):
diff --git a/src/datamodel_code_generator/parser/openapi.py b/src/datamodel_code_generator/parser/openapi.py
@@ -34,7 +34,7 @@
     JsonSchemaParser,
     get_model_by_path,
 )
-from datamodel_code_generator.reference import snake_to_upper_camel
+from datamodel_code_generator.reference import FieldNameResolver, snake_to_upper_camel
 from datamodel_code_generator.types import (
     DataType,
     DataTypeManager,
@@ -457,9 +457,12 @@ def parse_tags(
         """Parse operation tags."""
         return tags
 
+    _field_name_resolver: FieldNameResolver = FieldNameResolver()
+
     @classmethod
     def _get_model_name(cls, path_name: str, method: str, suffix: str) -> str:
-        camel_path_name = snake_to_upper_camel(path_name.replace("/", "_"))
+        normalized = cls._field_name_resolver.get_valid_name(path_name, ignore_snake_case_field=True)
+        camel_path_name = snake_to_upper_camel(normalized)
         return f"{camel_path_name}{method.capitalize()}{suffix}"
 
     def parse_all_parameters(
@@ -615,7 +618,7 @@ def parse_operation(
                 path=[*path, "tags"],
             )
 
-    def parse_raw(self) -> None:  # noqa: PLR0912
+    def parse_raw(self) -> None:  # noqa: PLR0912, PLR0915
         """Parse OpenAPI specification including schemas, paths, and operations."""
         for source, path_parts in self._get_context_source_path_parts():  # noqa: PLR1702
             if self.validation:
@@ -687,4 +690,36 @@ def parse_raw(self) -> None:  # noqa: PLR0912
                             [*path, operation_name],
                         )
 
+            if OpenAPIScope.Webhooks in self.open_api_scopes:
+                webhooks: dict[str, dict[str, Any]] = specification.get("webhooks", {})
+                webhooks_path = [*path_parts, "#/webhooks"]
+                for webhook_name, methods_ in webhooks.items():
+                    methods = self.get_ref_model(methods_["$ref"]) if "$ref" in methods_ else methods_
+                    webhook_parameters: list[dict[str, Any]] = []
+                    if "parameters" in methods:
+                        webhook_parameters = [
+                            self._get_ref_body(p["$ref"]) if "$ref" in p else p
+                            for p in methods["parameters"]
+                            if isinstance(p, dict)
+                        ]
+                    relative_webhook_name = webhook_name.removeprefix("/")
+                    if relative_webhook_name:
+                        path = [*webhooks_path, relative_webhook_name]
+                    else:  # pragma: no cover
+                        path = get_special_path("root", webhooks_path)
+                    for operation_name, raw_operation in methods.items():
+                        if operation_name not in OPERATION_NAMES:
+                            continue
+                        if webhook_parameters:
+                            if "parameters" in raw_operation:
+                                raw_operation["parameters"].extend(webhook_parameters)
+                            else:
+                                raw_operation["parameters"] = webhook_parameters.copy()
+                        if security is not None and "security" not in raw_operation:
+                            raw_operation["security"] = security
+                        self.parse_operation(
+                            raw_operation,
+                            [*path, operation_name],
+                        )
+
         self._resolve_unparsed_json_pointer()
diff --git a/tests/data/expected/main/openapi/openapi_non_operations_and_security.py b/tests/data/expected/main/openapi/openapi_non_operations_and_security.py
@@ -0,0 +1,18 @@
+# generated by datamodel-codegen:
+#   filename:  non_operations_and_security.yaml
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class Pet(BaseModel):
+    id: Optional[int] = None
+    name: Optional[str] = None
+
+
+class PetsGetResponse(BaseModel):
+    __root__: List[Pet]
diff --git a/tests/data/expected/main/openapi/openapi_webhooks.py b/tests/data/expected/main/openapi/openapi_webhooks.py
@@ -0,0 +1,21 @@
+# generated by datamodel-codegen:
+#   filename:  webhooks.yaml
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class Pet(BaseModel):
+    id: int
+    name: str
+    tag: Optional[str] = None
+
+
+class PetUpdate(BaseModel):
+    id: Optional[int] = None
+    name: Optional[str] = None
+    tag: Optional[str] = None
diff --git a/tests/data/expected/main/openapi/openapi_webhooks_with_parameters.py b/tests/data/expected/main/openapi/openapi_webhooks_with_parameters.py
@@ -0,0 +1,23 @@
+# generated by datamodel-codegen:
+#   filename:  webhooks_with_parameters.yaml
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class Pet(BaseModel):
+    id: int
+    name: str
+
+
+class PetNewPostParametersQuery(BaseModel):
+    X_Request_Id: Optional[str] = Field(None, alias='X-Request-Id')
+    X_Webhook_Id: str = Field(..., alias='X-Webhook-Id')
+
+
+class PetUpdatedPostParametersQuery(BaseModel):
+    X_Correlation_Id: str = Field(..., alias='X-Correlation-Id')
diff --git a/tests/data/openapi/non_operations_and_security.yaml b/tests/data/openapi/non_operations_and_security.yaml
@@ -0,0 +1,72 @@
+openapi: 3.1.0
+info:
+  title: API with Non-Operations and Security
+  version: 1.0.0
+security:
+  - api_key: []
+paths:
+  /pets:
+    summary: "This is not an operation"
+    description: "Also not an operation"
+    parameters:
+      - name: test_param
+        in: query
+        schema:
+          type: string
+    get:
+      summary: Get pets
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Pet'
+    post:
+      summary: Create pet
+      security:
+        - oauth2: ['write']
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+      responses:
+        '201':
+          description: Created
+webhooks:
+  pet.created:
+    summary: "Not an operation for webhooks"
+    description: "Also not an operation for webhooks"
+    post:
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+      responses:
+        '200':
+          description: Success
+components:
+  schemas:
+    Pet:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+  securitySchemes:
+    api_key:
+      type: apiKey
+      in: header
+      name: X-API-Key
+    oauth2:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: /token
+          scopes:
+            write: Write access
diff --git a/tests/data/openapi/webhooks.yaml b/tests/data/openapi/webhooks.yaml
@@ -0,0 +1,52 @@
+openapi: 3.1.0
+info:
+  title: Webhook Test API
+  version: 1.0.0
+webhooks:
+  pet.new:
+    post:
+      requestBody:
+        description: Information about a new pet in the system
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Pet"
+      responses:
+        '200':
+          description: Return a 200 status to indicate that the data was received successfully
+  pet.updated:
+    post:
+      requestBody:
+        description: Information about an updated pet
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PetUpdate"
+      responses:
+        '200':
+          description: Return a 200 status to indicate that the data was received successfully
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    PetUpdate:
+      type: object
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
diff --git a/tests/data/openapi/webhooks_with_parameters.yaml b/tests/data/openapi/webhooks_with_parameters.yaml
@@ -0,0 +1,55 @@
+openapi: 3.1.0
+info:
+  title: Webhook Test API with Parameters
+  version: 1.0.0
+webhooks:
+  pet.new:
+    parameters:
+      - name: X-Webhook-Id
+        in: query
+        required: true
+        schema:
+          type: string
+    post:
+      parameters:
+        - name: X-Request-Id
+          in: query
+          required: false
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Pet"
+      responses:
+        '200':
+          description: OK
+  pet.updated:
+    parameters:
+      - name: X-Correlation-Id
+        in: query
+        required: true
+        schema:
+          type: string
+    post:
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Pet"
+      responses:
+        '200':
+          description: OK
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
diff --git a/tests/main/openapi/test_main_openapi.py b/tests/main/openapi/test_main_openapi.py
@@ -2152,3 +2152,36 @@ def test_main_openapi_unquoted_null(output_file: Path) -> None:
         expected_file="unquoted_null.py",
         extra_args=["--output-model-type", "pydantic_v2.BaseModel"],
     )
+
+
+def test_main_openapi_webhooks(output_file: Path) -> None:
+    """Test OpenAPI generation with webhooks scope."""
+    run_main_and_assert(
+        input_path=OPEN_API_DATA_PATH / "webhooks.yaml",
+        output_path=output_file,
+        input_file_type="openapi",
+        assert_func=assert_file_content,
+        extra_args=["--openapi-scopes", "schemas", "webhooks"],
+    )
+
+
+def test_main_openapi_non_operations_and_security(output_file: Path) -> None:
+    """Test OpenAPI generation with non-operation fields and security inheritance."""
+    run_main_and_assert(
+        input_path=OPEN_API_DATA_PATH / "non_operations_and_security.yaml",
+        output_path=output_file,
+        input_file_type="openapi",
+        assert_func=assert_file_content,
+        extra_args=["--openapi-scopes", "schemas", "paths", "webhooks"],
+    )
+
+
+def test_main_openapi_webhooks_with_parameters(output_file: Path) -> None:
+    """Test OpenAPI generation with webhook-level and operation-level parameters."""
+    run_main_and_assert(
+        input_path=OPEN_API_DATA_PATH / "webhooks_with_parameters.yaml",
+        output_path=output_file,
+        input_file_type="openapi",
+        assert_func=assert_file_content,
+        extra_args=["--openapi-scopes", "schemas", "webhooks", "parameters"],
+    )
