OAI / OAI/OpenAPI-Specification
[Question] Optional response payloads
Nobody has claimed this yet.
- Dominant language
- Markdown
- Stars
- 31.2k
- Forks
- 9.2k
- Avg merge
- 6h 37m
- Merged PRs (30d)
- 27
Description
Hi,
How to express in OpenAPI that a response payload is optional for a given HTTP response code?
I noticed that the keyword "required: true/false" is applicable only to Request Body Object, but not to Response Body Object.
So, if a Response Body Object has a "content" field, does it indicate that a response payload is mandatory, and receiving an empty payload is considered as not allowed?
My goal is to express that a given HTTP response (mainly error codes, 4xx, 5xx) can be sent with, or without response payload. Per RFC 7231, the presence of response payloads in these error codes is encouraged (should) but it's not really mandated.
Thanks!
/Jesús.
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
Read the OpenAPI Response Object guidance and the RFC 7231 reference mentioned in the issue, focusing on whether a response with content permits an empty payload. Done means the specification clearly documents how to express responses that may include or omit a payload, especially for 4xx and 5xx status codes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100