Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Preliminary review - conformance to RFC9110 #3809

Closed
wants to merge 1 commit into from
Closed

Preliminary review - conformance to RFC9110 #3809

wants to merge 1 commit into from

Conversation

ioggstream
Copy link
Contributor

This PR

  • preliminary review to comply with HTTP specifications RFC9110

Notes

  • payload / body -> content

ioggstream
ioggstream commented May 15, 2024
View reviewed changes
versions/3.2.0.md
@@ -891,7 +891,7 @@ Field Name | Type | Description
<a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
<a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
<a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
<a name="operationRequestBody"></a>requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
<a name="operationRequestBody"></a>requestBody | [request content Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request content applicable for this operation. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request contents. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reference https://datatracker.ietf.org/doc/html/rfc9110

ioggstream
ioggstream commented May 15, 2024
View reviewed changes
versions/3.2.0.md
@@ -41,7 +41,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp
- [Operation Object](#operationObject)
- [External Documentation Object](#externalDocumentationObject)
- [Parameter Object](#parameterObject)
- [Request Body Object](#requestBodyObject)
- [request content Object](#requestBodyObject)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here and elsewere, retain Request Body

ioggstream
ioggstream commented May 15, 2024
View reviewed changes
versions/3.2.0.md
<a name="requestBodyContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | **REQUIRED**. The content of the request body. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
<a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `false`.
<a name="requestBodyDescription"></a>description | `string` | A brief description of the request content. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="requestBodyContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | **REQUIRED**. The content of the request content. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<a name="requestBodyContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | **REQUIRED**. The content of the request content. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
<a name="requestBodyContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | **REQUIRED**. The request content. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*

@handrews handrews requested a review from a team May 15, 2024 16:59
@handrews handrews added Housekeeping http Supporting HTTP features and interactions labels May 15, 2024
@handrews handrews added this to the v3.2.0 milestone May 17, 2024
@handrews handrews marked this pull request as draft May 20, 2024 16:24
@handrews
Copy link
Member

@ioggstream thanks for this! We are rearranging how our branches and directories are laid out which is about to make this PR invalid, so I'm closing it (and other 3.2.0 draft PRs). However, issue #3800 is tracking this, and you're welcome to re-submit once the branching/directory changes described in #3677 are finalized and implemented.

Otherwise, issue #3800 is in the 3.2.0 milestone already so we'll definitely look at it, and it will have a link to this PR for us to consider when deciding how to handle it. As you guessed with your later comments, we won't change "Request Body Object" to "Content Body Object" in a minor release, but we should consider the general vocabulary alignment.

@handrews handrews closed this Oct 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
Housekeeping http Supporting HTTP features and interactions
Projects
None yet
Milestone
v3.2.0
Development

Successfully merging this pull request may close these issues.
2 participants
@ioggstream @handrews