Support OpenAPI 3.1 top-level webhooks (#375)

[joseegman-idoneea]

What

Adds OpenAPI 3.1 top-level webhooks support — a checklist item of #375.

Stacked on #376 (array-valued type). This branch is based on that PR's branch, so until
#376 merges the diff here also shows its commit. Please merge #376 first, then this. Both
are part of the 3.1-support milestone, so the version stays 6.4.0 (no extra bump).

Background

OpenAPI 3.1 adds a top-level webhooks object: a map of named Path Item Objects describing
out-of-band requests. The generator only iterated paths, so webhooks were silently ignored —
no handler interface and no payload models were generated.

Change

• Add OpenApiUtil.mergeWebhooksIntoPaths(openApi), invoked right after parsing in
  OpenApiGenerator.processFile. Each webhook (keyed by name) is merged into paths under a
  "/"-prefixed key, so the existing path pipeline generates a handler interface for its
  operations and the request/response payload models. paths is created if the contract has
  none; existing paths entries are never overwritten.
• Add OpenApiUtil.WEBHOOKS constant.

This reuses the whole existing grouping / path-mapping / model-extraction pipeline rather than
adding a parallel one, keeping the change small.

Tests

New 3.1.0 webhooks-only fixture testWebhooks:

webhooks:
  newPet:
    post:
      operationId: newPetWebhook
      tags: [webhook]
      requestBody:
        content: { application/json: { schema: { $ref: '#/components/schemas/Pet' } } }
      responses: { '200': { description: Notification acknowledged } }

generates:

• NewPetApi.java — handler interface with POST /newPet (newPetWebhook) consuming PetDTO
• model/PetDTO.java — the payload model

OpenApiGeneratorTest: Tests run: 46, Failures: 0, Errors: 0; checkstyle:check — 0 violations.

Design note / scope

Webhooks are represented as endpoints in a generated handler interface (the common approach for a
webhook receiver), reusing the path pipeline; the primary value is that webhook payload
schemas become models. $ref'd webhook Path Items (external files) depend on the Path-Item-$ref
resolution in #372/#374; inline webhook Path Items are covered here. Remaining #375 items
(examples array, $ref siblings) are separate follow-ups.

🤖 Generated with Claude Code

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 15 complexity · 0 duplication

Metric	Results
Complexity	15
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}