Redocly / Redocly/redoc

Schema for callback and webhook includes readOnly property in the response payload instead of the writeOnly property

Open
#2,724 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Bug
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

Image Image

Additional context
I've created a minimal repo here

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.