swagger-api / swagger-api/swagger-ui

Schema for callbacks incorrectly omits readOnly and includes writeOnly properties

Open
#6,294 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

specification: 3.x type: bug
Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Q&A (please complete the following information)
  • OS: macOS
  • Browser: chrome
  • Version: 84
  • Method of installation: online
  • Swagger-UI version: not sure
  • Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration

Example Swagger/OpenAPI definition:

Describe the bug you're encountering

In brief the problem is that the UI shows the schema of webhook requests as though they were requests made to the API when in fact they contain responses from the API.

To reproduce...

In the schema above, a User has a name, an autogenerated id which is marked as readOnly (i.e. appears in responses but cannot be set) and a password which is marked as writeOnly (i.e. can be set but does not appear in responses).

In the UI it shows the schema for the GET request as:

[
  {
    "id": "string",
    "name": "string"
  }
]

And the schema for the POST request as:

{
  "name": "string",
  "password": "string"
}

So far so good.

But for the callback (which is nested inside the POST request) it shows the schema as:

{
  "name": "string",
  "password": "string"
}
Expected behavior

The callback is notifying the API user via a network request that the user was created (maybe this process takes a while). I would expect it to contain the name and the autogenerated id but not the private password. i.e. I would expect the callback request to have the same schema as a GET response not a POST request.

{
  "id": "string",
  "name": "string"
}
Additional context or thoughts

In OAS 3.1 readOnly and writeOnly have been removed from the spec and instead it defers to the JSON Schema spec which says:

If "readOnly" has a value of boolean true, it indicates that the value of the instance is managed exclusively by the owning authority, and attempts by an application to modify the value of this property are expected to be ignored or rejected by that owning authority.

[...]

If "writeOnly" has a value of boolean true, it indicates that the value is never present when the instance is retrieved from the owning authority. It can be present when sent to the owning authority to update or create the document (or the resource it represents), but it will not be included in any updated or newly created version of the instance.

Note the concept of an "owning authority" instead of the "request" and "response" wording used in OAS 3.0.

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

Use the linked gist and Swagger Editor reproduction as the starting point, then trace how the callback nested in the POST request is rendered versus the GET response and POST request schemas. Done means the callback displays name and id while omitting password, matching the expected example.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.