Schema for callback and webhook includes readOnly property in the response payload instead of the writeOnly property
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 25.9k
- Forks
- 2.4k
- Avg merge
- 13h 10m
- Merged PRs (30d)
- 4
Description
Describe the bug
I'm trying to reuse an object across a normal endpoint and the callback/another webhook. In the callbacks and webhooks, the writeOnly fields don't show anywhere, instead the readOnly fields show up in both the request and response. Interestingly, for the webhook response payload, the writeOnly field shows up in the example as expected, but not the schema definition.
Expected behavior
For normal endpoints I expect writeOnly fields to only show in the request and readOnly fields to show in the response. However for callbacks and webhooks, since the roles of the API server and the client are reversed (server is sending the request), I would expect the roles of readOnly and writeOnly to be reversed.
Do correct me if this assumption is wrong, this is what I understood from https://github.com/Redocly/redoc/issues/1540.
Minimal reproducible OpenAPI snippet(if possible)
openapi: 3.1.0
info:
title: API Documentation
description: API documentation with endpoints and webhooks using simpleObject schema
servers:
- url: https://api.mycompany.com
description: Production server
- url: https://staging.api.mycompany.com
description: Staging server
components:
schemas:
# Global schema object that will be used across all endpoints
simpleObject:
type: object
properties:
readOnly:
type: string
readOnly: true
description: A read-only string field
example: "This field is read-only"
writeOnly:
type: string
writeOnly: true
description: A write-only string field
example: "This field is write-only"
required:
- readOnly
- writeOnly
paths:
/api/data:
post:
summary: Create data entry
description: Creates a new data entry in the system
operationId: createDataEntry
tags:
- Data API
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/simpleObject'
responses:
'200':
description: Data entry created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/simpleObject'
callbacks:
dataProcessed:
'{$request.body#/callbackUrl}':
post:
summary: Data processing callback
description: Called when the data entry has been processed
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/simpleObject'
responses:
'200':
description: Callback acknowledged
content:
application/json:
schema:
$ref: '#/components/schemas/simpleObject'
webhooks:
dataUpdated:
post:
summary: Data updated webhook
description: Webhook triggered when data is updated in the system
operationId: dataUpdatedWebhook
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/simpleObject'
responses:
'200':
description: Webhook received and processed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/simpleObject'
Screenshots
Additional context
I've created a minimal repo here
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked minimal repository and reproduce the callback and webhook schemas from the supplied OpenAPI snippet, comparing them with the normal endpoint request and response schemas. Trace the schema rendering path for callbacks and webhooks. Done means their schema definitions show writeOnly and readOnly fields according to the expected reversed roles, consistently with the examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100