You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
openapi: 3.1.0info:
title: Example API with Webhookversion: 1.0.0paths:
/api/data:
get:
summary: Get dataresponses:
'200':
description: Successful responsecontent:
application/json:
schema:
$ref: '#/components/schemas/ComplexData'post:
summary: Create datarequestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ComplexData'responses:
'201':
description: Successfully createdcontent:
application/json:
schema:
$ref: '#/components/schemas/ComplexData'webhooks:
newData:
post:
summary: New data webhookdescription: Webhook for new datarequestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ComplexData'responses:
'200':
description: Webhook received successfullycomponents:
schemas:
NestedData:
type: objectproperties:
id:
type: integerreadOnly: truename:
type: stringinternalCode:
type: stringwriteOnly: truerequired:
- nameComplexData:
type: objectproperties:
title:
type: stringdescription:
type: stringcreatedAt:
type: stringformat: date-timereadOnly: truenestedData:
type: arrayitems:
$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 POSTdata 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.
Hi @dontic , this is a pickle :D readOnly is a weird one.
To be clear, you're looking at the generated JSON samples, when you say things are "missing"?
Hi @ponelat , I know... this topic is quite confusing and, because OpenAPI doesn't provide specific guidance, every UI tool is doing what they think is best, creating inconsistencies across them.
I'm not sure that I said there's anything missing but rather that, indeed, the JSON sample on the webhook should be the response representation of the schema rather than the request representation.
In the example of my original post you can how the sample on the GET endpoint response:
Compares to the JSON on the webhook payload:
When in reality the webhook payload should be the same data as the GET endpoint since you're sending that exact data through it, not requesting it.
Tools like Redoc and RapiDoc seem to have fixed this:
Q&A (please complete the following information)
5.17.14
Content & configuration
Example Swagger/OpenAPI definition:
Describe the bug you're encountering
Swagger UI seems to incorrectly display webhook payloads when using shared schemas with
readOnly
andwriteOnly
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 aGET
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 thedata
endpoint and thenewData
webhook payload.You can also see how the
newData
webhook payload is the same as the requested data from thePOST
data
endpoint.Expected behavior
When documenting webhooks, Swagger UI should use the same version of the schema as a
GET
definition, omittingwriteOnly
fields, displayingreadOnly
fields and any other relevant aspects of aGET
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:
The discussion seems to conclude that tools such as SwaggerUI should be the ones responsible to interpret this correctly.
Relevant issues describing similar problems:
Relevant issues and some fixes from other tools:
GET
specification tfranzel/drf-spectacular#1280The text was updated successfully, but these errors were encountered: