Incorrect Representation of Webhook Payloads

Q&A (please complete the following information)

• OS: N/A
• Browser: N/A
• Version: N/A
• Method of installation: N/A
• Swagger-UI version: 5.17.14
• Swagger/OpenAPI version: OpenAPI 3.1

Content & configuration

Example Swagger/OpenAPI definition:

openapi: 3.1.0
info:
  title: Example API with Webhook
  version: 1.0.0
paths:
  /api/data:
    get:
      summary: Get data
      responses:
        '200':
          description: Successful response
          content:
            application/json:    
              schema:
                $ref: '#/components/schemas/ComplexData'
    post:
      summary: Create data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComplexData'
      responses:
        '201':
          description: Successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplexData'
webhooks:
  newData:
    post:
      summary: New data webhook
      description: Webhook for new data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComplexData'
      responses:
        '200':
          description: Webhook received successfully

components:
  schemas:
    NestedData:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        internalCode:
          type: string
          writeOnly: true
      required:
        - name

    ComplexData:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
          readOnly: true
        nestedData:
          type: array
          items:
            $ref: '#/components/schemas/NestedData'
      required:
        - title
        - nestedData

Describe the bug you're encountering

Swagger UI seems to incorrectly display webhook payloads when using shared schemas with readOnly and writeOnly properties, or more complex schema definitions.

For webhooks, because the schema is defined from a POST perspective, the "request" version of the schema is displayed, where it should really be the "response" version of the schema. The same representation you would get from defining a GET endpoint with that schema.

This leads to inaccurate documentation of webhook payloads.

To reproduce...

You can reproduce this behavior by copying the OpenAPI definition above and pasting it in the swagger editor.

Then comparing the GET response from the data endpoint and the newData webhook payload.

You can also see how the newData webhook payload is the same as the requested data from the POST data endpoint.

Expected behavior

When documenting webhooks, Swagger UI should use the same version of the schema as a GET definition, omitting writeOnly fields, displaying readOnly fields and any other relevant aspects of a GET definition.

Impact

This issue causes confusion for API consumers, as the displayed webhook payload in Swagger UI does not accurately reflect the data that will be sent by the webhook in practice.

Possible Solution

Introduce a way to specify or infer the direction of data flow for webhooks, allowing Swagger UI to correctly interpret readOnly and writeOnly properties in this context.

Temporary workaround

The only decent workaround I found is to define specific schemas for webhook payloads. This is not ideal though as it causes code repetition and can clutter a definition while potentially confusing API consumers.

Additional context or thoughts

This issue was brought up in OpenAPI:

• https://github.com/OAI/OpenAPI-Specification/issues/3563

The discussion seems to conclude that tools such as SwaggerUI should be the ones responsible to interpret this correctly.

Relevant issues describing similar problems:

• https://github.com/swagger-api/swagger-ui/issues/8694
• https://github.com/swagger-api/swagger-ui/issues/6294

Relevant issues and some fixes from other tools:

• https://github.com/rapi-doc/RapiDoc/issues/727
• https://github.com/tfranzel/drf-spectacular/issues/1280
• https://github.com/Redocly/redoc/issues/1720

Start by reproducing the example in Swagger Editor and compare the GET response representation with the newData webhook payload, focusing on readOnly and writeOnly fields. Done means webhook documentation uses the response-style schema: readOnly fields are shown and writeOnly fields are omitted, without requiring a duplicate schema.