diff --git a/src/_data/sidebars/guides/openapi/v3-2.yml b/src/_data/sidebars/guides/openapi/v3-2.yml index f2746c20..3ce1f0fa 100644 --- a/src/_data/sidebars/guides/openapi/v3-2.yml +++ b/src/_data/sidebars/guides/openapi/v3-2.yml @@ -19,7 +19,7 @@ resources: link: /understanding-structure/api-servers/ - label: Paths and Operations link: /understanding-structure/paths-operations/ - - label: Parameters (Path, Query, Header, and Cookie) + - label: HTTP Parameters link: /understanding-structure/parameters/ - label: Parameter Serialization link: /understanding-structure/parameter-serialization/ diff --git a/src/_guides/openapi/openapi-format-overlays.md b/src/_guides/openapi/openapi-format-overlays.md index 137e16a8..156a68f9 100644 --- a/src/_guides/openapi/openapi-format-overlays.md +++ b/src/_guides/openapi/openapi-format-overlays.md @@ -30,7 +30,7 @@ Figuring out how to do all of this just from staring into an empty text editor c Copy in some OpenAPI into the box on the left. If you don’t have any handy why not use the [Train Travel API](https://github.com/bump-sh-examples/train-travel-api) by Bump.sh. -![](images/guides/openapi-format-overlays/new-openapi-in-playground.png) +![](/images/guides/openapi-format-overlays/new-openapi-in-playground.png) ### Step 2 - Open the Overlay section diff --git a/src/_guides/openapi/specification/v3.1/documentation/grouping-operations-with-tags.md b/src/_guides/openapi/specification/v3.1/documentation/grouping-operations-with-tags.md index e92a3d8d..352403d2 100644 --- a/src/_guides/openapi/specification/v3.1/documentation/grouping-operations-with-tags.md +++ b/src/_guides/openapi/specification/v3.1/documentation/grouping-operations-with-tags.md @@ -152,7 +152,7 @@ When you generate API documentation, you'll notice the documentation orders the ![How tags are ordered in generated API documentation](/images/guides/tags_order.png) [*See it live*](https://bump.sh/demo/doc/bump) -Note that [Bump.sh helps you order your endpoints and webhooks](/help/specifications-support/openapi-support/name-and-sort-resources/#group-by-tag) using a "Group by tag" operation. It is actually the default behaviour of Bump.sh when you have these tags defined and have not selected an other sorting option for your Bump.sh API documentation. +Note that [Bump.sh helps you order your endpoints and webhooks](/help/specifications-support/openapi-support/name-and-sort-resources/#group-by-tag) using a "Group by tag" operation. It is actually the default behavior of Bump.sh when you have these tags defined and have not selected an other sorting option for your Bump.sh API documentation. Now that you understand what tags are and their benefits, you'll see some best practices you should follow when using OpenAPI tags in API contracts. diff --git a/src/_guides/openapi/specification/v3.1/understanding-structure/parameter-serialization.md b/src/_guides/openapi/specification/v3.1/understanding-structure/parameter-serialization.md index d3002f28..f41c6979 100644 --- a/src/_guides/openapi/specification/v3.1/understanding-structure/parameter-serialization.md +++ b/src/_guides/openapi/specification/v3.1/understanding-structure/parameter-serialization.md @@ -200,9 +200,9 @@ This conflict is entirely avoided if you explicitly set `explode:false` on param It's basically identical to `style:form` with `explode:false`. The difference being, the separator used is not a comma, but a percent-encoded space "%20". -You'll notice there are no examples for any `type` that would be a single value. This is because its behaviour is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`. +You'll notice there are no examples for any `type` that would be a single value. This is because its behavior is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`. -`style:spaceDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behaviour for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default. +`style:spaceDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behavior for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default. ### Pipe Delimited @@ -223,13 +223,13 @@ If you still choose to use non-percent-encoded pipes, it would look like this: | ?pets=cat\|dog | ?pets=age\|2\|type\|dog | | ?pets=cat\|dog&hats=fedora | ?pets=age\|2\|type\|dog&hats=type\|fedora | -You'll notice there are no examples for any `type` that would be a single value. This is because its behaviour is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`. +You'll notice there are no examples for any `type` that would be a single value. This is because its behavior is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`. -`style:pipeDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behaviour for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default. +`style:pipeDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behavior for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default. ### Deep Object -`style:deepObject` is undefined for its default of `explode:false`. You must explicitly specify `explode:true` for any defined behaviour. +`style:deepObject` is undefined for its default of `explode:false`. You must explicitly specify `explode:true` for any defined behavior. You may be able to use a normal square brackets "[" and "]" but they are in the list of [RFC3986's Reserved Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2). As such, it may not work in some environments. @@ -247,9 +247,9 @@ For maximum interoperability it is safer to have them percent-encoded: | ?pets%5Bage%5D=2&pets%5Btype%5D=dog | | ?pets%5Bage%5D=2&pets%5Btype%5D=dog&hats%5Btype%5D=fedora | -Unsurprisingly, it only has defined behaviour for an `object`. This `style` is quite different from any other, even with `explode:true` the `name`, key and value are all specified. This makes it useful for avoiding the potential name conflicts objects could cause with `style:form`, `explode:true`. +Unsurprisingly, it only has defined behavior for an `object`. This `style` is quite different from any other, even with `explode:true` the `name`, key and value are all specified. This makes it useful for avoiding the potential name conflicts objects could cause with `style:form`, `explode:true`. -Just bear in mind the name is misleading, despite being called a `deepObject`, there is no defined behaviour for nested arrays or objects. This is the same for every `style` `in:query`. +Just bear in mind the name is misleading, despite being called a `deepObject`, there is no defined behavior for nested arrays or objects. This is the same for every `style` `in:query`. ## Header Parameters @@ -429,7 +429,7 @@ Now our URL will look like this: Here I've stated that my `schema` can be `anyOf` the following: an object or a string, in `style:deepObject`. You may have spotted the problem already: - If our user specifies an object, this works as expected: `/trips?station[preferred]=gatwick&station[fallback]=london`. -- What if our user specifies a string? It's undefined, `deepObject` only has defined behaviour for objects. +- What if our user specifies a string? It's undefined, `deepObject` only has defined behavior for objects. You cannot apply `style` on a per-`schema` basis. Your `style` needs to work for all possible variations of your parameter. If you intend to use `anyOf`, `allOf` or `oneOf` make doubly sure your choice of `style` works for every option. diff --git a/src/_guides/openapi/specification/v3.2/advanced/callbacks-webhooks.md b/src/_guides/openapi/specification/v3.2/advanced/callbacks-webhooks.md index 0f4936b6..37251fe9 100644 --- a/src/_guides/openapi/specification/v3.2/advanced/callbacks-webhooks.md +++ b/src/_guides/openapi/specification/v3.2/advanced/callbacks-webhooks.md @@ -103,7 +103,7 @@ Content-Type: application/json } ``` -The callbackURL could be in headers or could be composed of various other bits of data in the request, take a look at OpenAPI v3.1's [runtime expressions](https://spec.openapis.org/oas/v3.1.0#runtime-expressions) syntax to get more advanced. +The callbackURL could be in headers or could be composed of various other bits of data in the request, take a look at OpenAPI's [runtime expressions](https://spec.openapis.org/oas/v3.1.0#runtime-expressions) syntax to get more advanced. Once you've got a callback named and figured out where the URL is going, the rest of the OpenAPI is going to feel very familiar, only it's backwards. diff --git a/src/_guides/openapi/specification/v3.2/advanced/error-formats.md b/src/_guides/openapi/specification/v3.2/advanced/error-formats.md index 552100e3..ad8d5d30 100644 --- a/src/_guides/openapi/specification/v3.2/advanced/error-formats.md +++ b/src/_guides/openapi/specification/v3.2/advanced/error-formats.md @@ -1,7 +1,7 @@ --- title: Handling Error Formats authors: phil -excerpt: Describing HTTP errors efficiently in OpenAPI v3.1. +excerpt: Describing HTTP errors efficiently in OpenAPI v3.2. date: 2024-08-07 --- diff --git a/src/_guides/openapi/specification/v3.2/advanced/json-streaming.md b/src/_guides/openapi/specification/v3.2/advanced/json-streaming.md index 1d2e7a10..3c87dcdb 100644 --- a/src/_guides/openapi/specification/v3.2/advanced/json-streaming.md +++ b/src/_guides/openapi/specification/v3.2/advanced/json-streaming.md @@ -348,4 +348,5 @@ Whatever the schema is, it can be defined using the standard JSON Schema keyword ## Further Reading -You can find details in the **OpenAPI Specification v3.2.0** under [Media Types Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.2.0.md#media-type-object) and look for `itemSchema`. +- [Learn OpenAPI: Sequential Media Types](https://learn.openapis.org/specification/media-types.html) +- [OpenAPI Specification v3.2.0: Media Types Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.2.0.md#media-type-object) diff --git a/src/_guides/openapi/specification/v3.2/advanced/multipart-form-data.md b/src/_guides/openapi/specification/v3.2/advanced/multipart-form-data.md index 5c5581cd..656d8d68 100644 --- a/src/_guides/openapi/specification/v3.2/advanced/multipart-form-data.md +++ b/src/_guides/openapi/specification/v3.2/advanced/multipart-form-data.md @@ -169,7 +169,7 @@ requestBody: type: integer ``` -Take a look at the OpenAPI v3.1 Specification to learn more about the [Encoding Object](https://spec.openapis.org/oas/v3.1.0#encoding-object), and see how to handle custom headers and even "styles" and "explode" to handle complex data expressed in a string form. +Take a look at the OpenAPI v3.2 Specification to learn more about the [Encoding Object](https://spec.openapis.org/oas/v3.2.0#encoding-object), and see how to handle custom headers and even "styles" and "explode" to handle complex data expressed in a string form. > Multipart form data is only one way to handle file uploads, so read the [File Uploads](_guides/openapi/specification/v3.2/advanced/file-uploads.md) guide to see other ways to do it. {: .info } diff --git a/src/_guides/openapi/specification/v3.2/advanced/security.md b/src/_guides/openapi/specification/v3.2/advanced/security.md index 54297298..447ed943 100644 --- a/src/_guides/openapi/specification/v3.2/advanced/security.md +++ b/src/_guides/openapi/specification/v3.2/advanced/security.md @@ -13,7 +13,7 @@ OpenAPI uses the term "security scheme" to cover both authentication and authori - **Authentication:** Who is this user, are they who they say they are. - **Authorization:** What data can this user see, what actions can they take. -OpenAPI v3.1 lets you describe APIs protected using the following security schemes: +OpenAPI lets you describe APIs protected using the following security schemes: - HTTP authentication schemes (anything using the `Authorization` header) - Basic @@ -207,7 +207,7 @@ In this example, the `/bookings` path requires the `OAuth2ReadWrite` security sc OpenID Connect is an identity layer built on top of OAuth 2.0 that allows clients to verify the identity of end-users based on the authentication performed by an authorization server. It provides a standardized way to authenticate users and obtain their identity information, such as name, email, and profile picture. -In OpenAPI v3.1, you can describe OpenID Connect authentication using the following example: +In OpenAPI v3.x, you can describe OpenID Connect authentication using the following example: ```yaml OpenIDConnect: @@ -324,7 +324,7 @@ All other paths will continue to be secured regardless of what order they're in. You might have noticed the empty array showing up: `HttpBearerToken: []`. This empty array is where "scopes" go. -Scopes allow you to define fine-grained permissions within some types of security schema that support them, and in OpenAPI v3.1 that means OAuth 2 and OpenID Connect. +Scopes allow you to define fine-grained permissions within some types of security schema that support them, and in OpenAPI v3.x that means OAuth 2 and OpenID Connect. Each security scheme can have its own set of scopes, which can be used to control access to specific resources or actions. diff --git a/src/_guides/openapi/specification/v3.2/data-models/examples.md b/src/_guides/openapi/specification/v3.2/data-models/examples.md index 34b14eef..1304d6bb 100644 --- a/src/_guides/openapi/specification/v3.2/data-models/examples.md +++ b/src/_guides/openapi/specification/v3.2/data-models/examples.md @@ -20,7 +20,7 @@ There are three main types of examples: ## Schema Examples -The [schema object](_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md) is used all over in OpenAPI, for requests and responses, parameters, and headers. A schema in OpenAPI v3.1 can add an example for an entire schema, part of a schema, or a single specific property, which is either confusing or flexible, depending on how you see the world. +The [schema object](_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md) is used all over in OpenAPI, for requests and responses, parameters, and headers. A schema in OpenAPI v3.x can add an example for an entire schema, part of a schema, or a single specific property, which is either confusing or flexible, depending on how you see the world. Here's an example of the `examples` keyword being used for specific properties inside an object. @@ -97,7 +97,7 @@ For more on these schema examples, head over to the [Learn JSON Schema: Examples ## Media Type Examples -The [Media Type Object](https://spec.openapis.org/oas/v3.1.0#media-type-object) is the same object that defines the request body and each response underneath the `application/json` or whichever other content type is being defined. +The [Media Type Object](https://spec.openapis.org/oas/v3.2.0#media-type-object) is the same object that defines the request body and each response underneath the `application/json` or whichever other content type is being defined. This type of example allows you to create an entire request or response example, and you have a choice between two two keywords: `example` or `examples`. There is more than just an `s` difference between these keywords, they're different shapes too. `example` is singular example which just contains the actual example value. @@ -176,7 +176,7 @@ The summary name is optional, but is a great place to put human readable names i ![](/images/changelog/multiple_examples.jpg) -Notice that these examples are all defined _next_ to the `schema` keyword, not _inside_ it. Examples outside the schema object are an object with names, examples inside the schema object are just a list (array) which have no names. For clarity you can check the OpenAPI v3.1 Specification, looking at the [Media Type Object](https://spec.openapis.org/oas/v3.1.0#media-type-object) and the [Schema Object](https://spec.openapis.org/oas/v3.1.0#schema-object). +Notice that these examples are all defined _next_ to the `schema` keyword, not _inside_ it. Examples outside the schema object are an object with names, examples inside the schema object are just a list (array) which have no names. For clarity you can check the OpenAPI v3.2 Specification, looking at the [Media Type Object](https://spec.openapis.org/oas/v3.2.0#media-type-object) and the [Schema Object](https://spec.openapis.org/oas/v3.2.0#schema-object). Here's a quick example of all the examples so you know where to start. @@ -200,7 +200,7 @@ requestBody: ## Parameter Examples -The OpenAPI v3.1 Parameter Object describes path parameters, query parameters, headers, etc. Since OpenAPI v3.0 They can have `examples` or an `example`, which work the same as the media type examples. They can also have a `schema`, which means they can have schema `examples` just like we talked about above. +The OpenAPI v3.2 Parameter Object describes path parameters, query parameters, headers, etc. Since OpenAPI v3.0 They can have `examples` or an `example`, which work the same as the media type examples. They can also have a `schema`, which means they can have schema `examples` just like we talked about above. ```yaml /params: @@ -254,7 +254,7 @@ Some mocking tools [like Microcks][microcks] might prefer you use named examples ## Example of All Examples -Let's go on an adventure through all the types of examples available in OpenAPI v3.1, with a bunch of Adventure Time characters with random coordinates of their last known locations. +Let's go on an adventure through all the types of examples available in OpenAPI v3.2, with a bunch of Adventure Time characters with random coordinates of their last known locations. ```yaml openapi: 3.2.0 @@ -344,3 +344,7 @@ What are we trying to achieve in doing this? We want the docs and mocks to have This lets tools know that false is the default state for this property, which will make documentation more clear, help mock servers act more consistently, and can even make any code generated from OpenAPI work as expected. The `default` keyword is therefore quite similar to `examples` within a schema object, as it can introduce concrete values into the schema which can be used for all sorts of tooling, but it's more functional. + + + + diff --git a/src/_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md b/src/_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md index 0c6dc19a..9e8ace0f 100644 --- a/src/_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md +++ b/src/_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md @@ -10,7 +10,7 @@ date: 2025-05-16 One of the most important parts of OpenAPI is the `schema` object. Schema objects are used to describe HTTP request and response bodies, parameters, headers, and all sorts of other data, whether its JSON, XML, or primitive types like integers and strings. -> If you're familiar with JSON Schema, you'll be right at home here, because OpenAPI v3.1 uses JSON Schema (draft 2020-12). For those who have not used JSON Schema before, that's ok, follow along. +> If you're familiar with JSON Schema, you'll be right at home here, because OpenAPI v3.1 onward is compatible with JSON Schema. For those who have not used JSON Schema before, that's ok, follow along. {: .info } The first thing to learn about a schema is the `type` keyword, which can be one or more of the following types: @@ -102,7 +102,7 @@ items: format: int32 ``` -The full list of formats defined in the JSON Schema Validation that OpenAPI v3.1 relies upon: +The full list of formats defined in the JSON Schema Validation that OpenAPI v3.2 uses: - date-time: A string instance is valid against this attribute if it is a valid representation according to the "date-time" production as defined in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339). diff --git a/src/_guides/openapi/specification/v3.2/data-models/schema-composition.md b/src/_guides/openapi/specification/v3.2/data-models/schema-composition.md index 0609b16a..a65d28a9 100644 --- a/src/_guides/openapi/specification/v3.2/data-models/schema-composition.md +++ b/src/_guides/openapi/specification/v3.2/data-models/schema-composition.md @@ -8,7 +8,7 @@ date: 2025-07-24 - TOC {:toc} -In OpenAPI v3.1 and JSON Schema, you can use `oneOf`, `allOf`, and `anyOf` keywords to handle composition, which is the concept of combining multiple schemas and subschemas in various ways to handle polymorphism, or "extending" other schemas to add more criteria. +From OpenAPI v3.1, you can use the JSON Schema keywords `oneOf`, `allOf`, and `anyOf` to handle composition, which is the concept of combining multiple schemas and subschemas in various ways to handle polymorphism, or "extending" other schemas to add more criteria. ## What are oneOf, anyOf, and allOf? @@ -161,4 +161,4 @@ content: $ref: '#/components/schemas/Links-Self' ``` -These schema composition keywords provide flexibility and allow you to define complex data structures and validation rules in OpenAPI v3.1 and JSON Schema, which becomes more useful as you start to [improve reuse across one or more API](_guides/openapi/specification/v3.2/advanced/splitting-documents-with-ref.md). +These schema composition keywords provide flexibility and allow you to define complex data structures and validation rules in OpenAPI and JSON Schema, which becomes more useful as you start to [improve reuse across one or more API](_guides/openapi/specification/v3.2/advanced/splitting-documents-with-ref.md). diff --git a/src/_guides/openapi/specification/v3.2/documentation/grouping-operations-with-tags.md b/src/_guides/openapi/specification/v3.2/documentation/grouping-operations-with-tags.md index 86567c29..45986c5d 100644 --- a/src/_guides/openapi/specification/v3.2/documentation/grouping-operations-with-tags.md +++ b/src/_guides/openapi/specification/v3.2/documentation/grouping-operations-with-tags.md @@ -142,7 +142,7 @@ When you generate API documentation, you'll notice the documentation orders the ![How tags are ordered in generated API documentation](/images/guides/tags_order.png) [*See it live*](https://bump.sh/demo/doc/bump) -Note that [Bump.sh helps you order your endpoints and webhooks](/help/specifications-support/openapi-support/name-and-sort-resources/#group-by-tag) using a "Group by tag" operation. It is actually the default behaviour of Bump.sh when you have these tags defined and have not selected an other sorting option for your Bump.sh API documentation. +Note that [Bump.sh helps you order your endpoints and webhooks](/help/specifications-support/openapi-support/name-and-sort-resources/#group-by-tag) using a "Group by tag" operation. It is actually the default behavior of Bump.sh when you have these tags defined and have not selected an other sorting option for your Bump.sh API documentation. Now that you understand what tags are and their benefits, you'll see some best practices you should follow when using OpenAPI tags in API contracts. @@ -257,7 +257,7 @@ tags: ### Define All Your OpenAPI Tags Before Use -The OpenAPI specification [doesn't require you to define all your tags in the root Tag Object of your API contract](https://spec.openapis.org/oas/v3.1.0#:~:text=A%20list%20of,MUST%20be%20unique). This means you can add a tag to an endpoint without listing it in the root Tag Object, but this is a bad idea. You won't be able to control what order the OpenAPI tags should appear in, and you won't be able to add a description or provide a link to external documentation for that tag. It can also confuse developers browsing the API documentation as they won't see a list of all the tags used in the API description. +The OpenAPI specification [doesn't require you to define all your tags in the root Tag Object of your API contract](https://spec.openapis.org/oas/v3.2.0#:~:text=A%20list%20of,MUST%20be%20unique). This means you can add a tag to an endpoint without listing it in the root Tag Object, but this is a bad idea. You won't be able to control what order the OpenAPI tags should appear in, and you won't be able to add a description or provide a link to external documentation for that tag. It can also confuse developers browsing the API documentation as they won't see a list of all the tags used in the API description. As an example, consider the code snippet below where the `Previews` and the `Ping` tags has not been included in the root Tag Object: diff --git a/src/_guides/openapi/specification/v3.2/extending/extensions.md b/src/_guides/openapi/specification/v3.2/extending/extensions.md index 4c0d548c..67224587 100644 --- a/src/_guides/openapi/specification/v3.2/extending/extensions.md +++ b/src/_guides/openapi/specification/v3.2/extending/extensions.md @@ -8,7 +8,7 @@ date: 2024-03-20 - TOC {:toc} -OpenAPI v3.1 has a concept of [Specification Extensions](https://spec.openapis.org/oas/v3.1.0#specification-extensions) which are additional properties not specified by the OpenAPI specification. These are a chance to customize and integrate tools from documentation to API gateways, all hooking into the OpenAPI document and storing information important to them in the form of extra properties that will be ignored by other tooling. +OpenAPI v3.x has the concept of [Specification Extensions](https://spec.openapis.org/oas/v3.2.0#specification-extensions) which are additional properties not specified by the OpenAPI specification. These are a chance to customize and integrate tools from documentation to API gateways, all hooking into the OpenAPI document and storing information important to them in the form of extra properties that will be ignored by other tooling. All those properties start with the `x-` naming convention to be identified as “eXternal” from the OpenAPI specification. diff --git a/src/_guides/openapi/specification/v3.2/understanding-structure/http-requests.md b/src/_guides/openapi/specification/v3.2/understanding-structure/http-requests.md index 31e01e49..fa9cb0c1 100644 --- a/src/_guides/openapi/specification/v3.2/understanding-structure/http-requests.md +++ b/src/_guides/openapi/specification/v3.2/understanding-structure/http-requests.md @@ -8,12 +8,27 @@ date: 2025-07-09 - TOC {:toc} -Any API handling use-cases more advanced that purely fetching data will need to define a HTTP request body. `POST`, `PATCH`, `PUT`, `QUERY`, etc. all allow a HTTP client to send a body: often JSON or XML. This allows for more information to be sent rather than just query string parameters, which have limits. +HTTP requests are a fundamental part of any API. They allow clients to send data to the server, whether that’s creating new resources, updating existing ones, or performing complex queries. -The request body can be used for: +OpenAPI 3.x provides a robust way to define these requests, and OpenAPI v3.2 introduces even more capabilities to handle a wider range of scenarios. + +Supported HTTP Methods: + +- `GET` +- `PATCH` +- `POST` +- `PUT` +- `DELETE` +- `HEAD` +- `OPTIONS` +- `TRACE` +- `QUERY` +- Additional custom methods via `additionalOperations` + +The HTTP request can also include a body: usually JSON or XML. The request body can be used for: - Creating new resources (e.g.: booking a train ticket) -- Updating existing resources (e.g.: updating that booking) +- Updating existing resources (e.g.: updating or cancelling that booking) - Uploading files (e.g.: uploading an image to your railcard) ## Structure of Request Bodies @@ -63,7 +78,6 @@ paths: Here the `requestBody` object defines two important properties: - `required: true` - indicates that the request body is mandatory for this operation. - - `content` - specifies that the request body should be in `application/json` format with the following `schema`. The schema defines the structure of the request body, including properties like `passenger_name`, `train_id`, `date`, and `seat_preference`. This can be defined inline like this, or it can use `components` to share an [existing schema](_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md) and reduce repetition. @@ -104,6 +118,108 @@ The `schema` then defines the structure of the request body, which demonstrates If multiple properties could be updated, you would define all the properties that could be updated, then show off some [examples](_guides/openapi/specification/v3.2/data-models/examples.md) for common use-cases of things users might want to do. +## Query Requests + +OpenAPI 3.2 adds native support for the `QUERY` HTTP method, which is designed to support complex queries that don’t fit neatly in URL query strings. + +Prior to the HTTP Query method it was common for people to add infinite query string parameters like `?origin=london&destination=paris&has_dogs=true`, or to try and create some sort of query syntax using a standard or home-grown DSL like `?filter=origin:london,destination:paris,has_dogs:true`, but these syntaxes struggle when it comes to `is null`, `not null`, or `>=10`. Putting the query into the body allows for more advanced structures using JSON for example. + +```yaml +paths: + /products: + query: + summary: Product search + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + filter: + type: object + required: [field, value] + properties: + field: + type: string + examples: [id] + value: + type: string + examples: [abc123] + operator: + type: string + example: "!=" + sort: + type: object + description: A hash of field names as keys, and direction as a value (asc or desc). + additionalProperties: + type: string + enum: [asc, desc] + examples: + - price: "desc" + published: "desc" + + responses: + '200': + description: Search results +``` + +Within a simple structure like this, searching and filtering can be handled with a more useful + +```http +QUERY /feed +Content-Type: application/json + +{ + "q": "foo", + "limit": 10, + "sort": { + "price": "desc", + "published": "asc" + }, + "filter": [ + { + "field": "origin", + "value": "london" + }, + { + "field": "destination", + "value": "paris" + }, + { + "field": "price", + "value": "60.00", + "operator": "<=" + } + ] +} +``` + +## Additional HTTP Methods + +Use `additionalOperations` for HTTP methods not covered by standard OpenAPI operations. + +For example, maybe an API is using the `PURGE` HTTP method to remove cached resources from the an API behind a cache proxy like [Varnish](https://varnish-cache.org/docs/3.0/tutorial/purging.html). + +```yaml +paths: + /tickets/{ticketId}: + parameters: + - name: ticketId + in: path + required: true + schema: + type: string + additionalOperations: + PURGE: + summary: Purge a ticket from the cache + responses: + '204': + description: Ticket purged from cache +``` + +This allows for full support of any HTTP method you can think of, allowing OpenAPI v3.2 to go beyond only supporting the core HTTP methods. + ## File Uploads & Multipart Forms HTTP requests can also cover more advanced scenarios like [file uploads](_guides/openapi/specification/v3.2/advanced/file-uploads.md) and [multipart form data](_guides/openapi/specification/v3.2/advanced/multipart-form-data.md), which have their own guides in the advanced section. diff --git a/src/_guides/openapi/specification/v3.2/understanding-structure/parameter-serialization.md b/src/_guides/openapi/specification/v3.2/understanding-structure/parameter-serialization.md index 383ebf73..22214898 100644 --- a/src/_guides/openapi/specification/v3.2/understanding-structure/parameter-serialization.md +++ b/src/_guides/openapi/specification/v3.2/understanding-structure/parameter-serialization.md @@ -8,7 +8,7 @@ date: 2024-07-04 - TOC {:toc} -[Parameters](_guides/openapi/specification/v3.2/understanding-structure/parameters.md) not only define what inputs your API accepts, they also define the format your API expects to receive them in, i.e. how you would like it serialized. +[Parameters](_guides/openapi/specification/v3.2/understanding-structure/parameters.md) not only define what inputs your API accepts, they also define the format your API expects to receive them in, i.e. how those parameters should serialized. There are two keywords concerning serialization: @@ -199,9 +199,9 @@ This conflict is entirely avoided if you explicitly set `explode:false` on param It's basically identical to `style:form` with `explode:false`. The difference being, the separator used is not a comma, but a percent-encoded space "%20". -You'll notice there are no examples for any `type` that would be a single value. This is because its behaviour is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`. +You'll notice there are no examples for any `type` that would be a single value. This is because its behavior is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`. -`style:spaceDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behaviour for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default. +`style:spaceDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behavior for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default. ### Pipe Delimited @@ -222,13 +222,13 @@ If you still choose to use non-percent-encoded pipes, it would look like this: | ?pets=cat\|dog | ?pets=age\|2\|type\|dog | | ?pets=cat\|dog&hats=fedora | ?pets=age\|2\|type\|dog&hats=type\|fedora | -You'll notice there are no examples for any `type` that would be a single value. This is because its behaviour is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`. +You'll notice there are no examples for any `type` that would be a single value. This is because its behavior is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`. -`style:pipeDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behaviour for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default. +`style:pipeDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behavior for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default. ### Deep Object -`style:deepObject` is undefined for its default of `explode:false`. You must explicitly specify `explode:true` for any defined behaviour. +`style:deepObject` is undefined for its default of `explode:false`. You must explicitly specify `explode:true` for any defined behavior. You may be able to use a normal square brackets "[" and "]" but they are in the list of [RFC3986's Reserved Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2). As such, it may not work in some environments. @@ -246,9 +246,9 @@ For maximum interoperability it is safer to have them percent-encoded: | ?pets%5Bage%5D=2&pets%5Btype%5D=dog | | ?pets%5Bage%5D=2&pets%5Btype%5D=dog&hats%5Btype%5D=fedora | -Unsurprisingly, it only has defined behaviour for an `object`. This `style` is quite different from any other, even with `explode:true` the `name`, key and value are all specified. This makes it useful for avoiding the potential name conflicts objects could cause with `style:form`, `explode:true`. +Unsurprisingly, it only has defined behavior for an `object`. This `style` is quite different from any other, even with `explode:true` the `name`, key and value are all specified. This makes it useful for avoiding the potential name conflicts objects could cause with `style:form`, `explode:true`. -Just bear in mind the name is misleading, despite being called a `deepObject`, there is no defined behaviour for nested arrays or objects. This is the same for every `style` `in:query`. +Just bear in mind the name is misleading, despite being called a `deepObject`, there is no defined behavior for nested arrays or objects. This is the same for every `style` `in:query`. ## Header Parameters @@ -428,8 +428,14 @@ Now our URL will look like this: Here I've stated that my `schema` can be `anyOf` the following: an object or a string, in `style:deepObject`. You may have spotted the problem already: - If our user specifies an object, this works as expected: `/trips?station[preferred]=gatwick&station[fallback]=london`. -- What if our user specifies a string? It's undefined, `deepObject` only has defined behaviour for objects. +- What if our user specifies a string? It's undefined, `deepObject` only has defined behavior for objects. You cannot apply `style` on a per-`schema` basis. Your `style` needs to work for all possible variations of your parameter. If you intend to use `anyOf`, `allOf` or `oneOf` make doubly sure your choice of `style` works for every option. As always, the best option is to minimise your use of complex parameters, keep it simple. + +### Switching DeepObject to Querystring Parameters + +In OpenAPI v3.2, a new parameter location was added: `in: querystring` to help avoid complexity in `deepObject` parameters. Instead of trying to fit everything into a single parameter, you can now define multiple parameters in the querystring using the same `schema`, which can even have different content types. + +**Learn more about Querystring Parameters in the [HTTP Parameters guide](_guides/openapi/specification/v3.2/understanding-structure/parameters.mds).** diff --git a/src/_guides/openapi/specification/v3.2/understanding-structure/parameters.md b/src/_guides/openapi/specification/v3.2/understanding-structure/parameters.md index f4349c80..067bd99f 100644 --- a/src/_guides/openapi/specification/v3.2/understanding-structure/parameters.md +++ b/src/_guides/openapi/specification/v3.2/understanding-structure/parameters.md @@ -8,7 +8,7 @@ date: 2025-07-04 - TOC {:toc} -Parameters in OpenAPI v3.1 are a fundamental part of creating an API specification, allowing you to define the inputs your API can accept. +Parameters in OpenAPI are a fundamental part of creating an API specification, allowing you to define the inputs your API can accept. Parameters fall into one of a few types: @@ -17,13 +17,20 @@ Parameters fall into one of a few types: - **Header Parameters:** Included in the request header, e.g., `Acme-Custom-Header: Value`. - **Cookie Parameters:** Passed in the request cookies. -> In previous versions of OpenAPI the entire request body and form data would all be sent as parameters, but since OpenAPI v3.0 this has been moved to the content object. Learn more in [HTTP Requests](_guides/openapi/specification/v3.2/understanding-structure/http-requests.md). -{: .info } - Each parameter in OpenAPI is defined with specific attributes such as `name`, `in` (location), `required`, `description`, and `schema` (for defining data types and validation rules). Defining parameters with these keywords allows documentation to show example how HTTP requests should be constructed making life easier for the client, but also make sure machines know what to do with it, making SDKs and server-side validation a whole lot more powerful. ## Parameter Types +There are five main types of parameters in OpenAPI v3.2, each serving a different purpose in the context of an HTTP request. + +- Path Parameters - `in: path` +- Query Parameters -`in: query` +- Header Parameters - `in: header` +- Cookie Parameters - `in: cookie` +- OpenAPI 3.2 added Querystring Parameters `in: querystring` + +That new addition is a little confusing as the names are so similar, but we'll cover that in a bit. + ### Path Parameters The first type of parameter to get the hang of is path parameters. @@ -47,7 +54,7 @@ Here is one required path parameter, `bookingId`, with its `name` matching `{boo > Path parameters have to be marked as `required: true` because they're in the path, and if its missing it would break especially if the variable was between two other segments, e.g: `/bookings/{bookingId}/payment` would become `/bookings//payment` if the value was empty and that's going to be confusing. {: .warning } -OpenAPI v3.1 is very particular about allowed characters: +OpenAPIis very particular about allowed characters: > The value for these path parameters MUST NOT contain any unescaped "generic syntax" characters described by RFC3986: forward slashes (/), question marks (?), or hashes (#). @@ -154,6 +161,72 @@ paths: example: 5 ``` +### Querystring Parameters + +OpenAPI v3.2 added support for a new type of parameter called `querystring` parameters. These are similar to query parameters, but they allow for more complex structures to be sent in the query string. + +Unlike `in: query`, with `in: querystring` the entire query string is treated as a single parameter with complex structure. This means that combinations of query parameters can be expressed using a well-defined Schema object: + +```yaml +paths: + /search: + get: + parameters: + - name: advancedQuery + in: querystring + content: + application/x-www-form-urlencoded: + schema: + type: object + properties: + filters: + type: object + sorting: + type: array + items: + type: string +``` + +In HTTP that would look like this: + +```http +GET /search?filters[origin]=london&filters[destination]=paris + &filters[has_dogs]=true&sorting[]=price&sorting[]=duration +``` + +It also allows for JSON encoded query strings: + +```yaml +paths: + /search: + get: + summary: Search for items + parameters: + - name: filter + in: querystring + content: + application/json: + schema: + type: object + properties: + origin: + type: string + destination: + type: string + has_dogs: + type: boolean + +``` + +In HTTP that would look like this: + +```http +GET /search?filter={"origin":"london","destination":"paris","has_dogs":true} +``` + +Handling advanced query strings like this used to rely on trickery with a combination of [parameter serialization](_guides/openapi/specification/v3.2/understanding-structure/parameter-serialization.md) options most users (and tooling) seemed to struggle with. This new `querystring` parameter type makes it much clearer what is going on, and allows for more complex structures to be expressed in a way that is easier to understand. + +Thanks to this new approach giving you the full power of the `schema` keyword, you can re-use and combine sets of query parameters with allOf, you can make them conditional and interdependent with `if`/`then`/`else`, and support [polymorphism with `oneOf`/`anyOf`](_guides/openapi/specification/v3.2/data-models/schema-composition.md). You can even forbid unexpected parameters with `additionalProperties: false` if you want to be strict about what is allowed. ## Defining Parameters for Multiple Operations diff --git a/src/_help/customization-options/operations-navigation.md b/src/_help/customization-options/operations-navigation.md index 7ed0b1f5..7cc25895 100644 --- a/src/_help/customization-options/operations-navigation.md +++ b/src/_help/customization-options/operations-navigation.md @@ -13,7 +13,7 @@ From the “Customize UI” tab in your documentation settings, you can select a By default, Bump.sh analyzes your API definition and suggests the most suitable sorting mode, either by paths or by tags. -If first-level field `tags` are present at the [root of your OpenAPI document object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#openapi-object), Bump.sh will use `Group by tags` as a default documentation generation behaviour. +If first-level field `tags` are present at the [root of your OpenAPI document object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#openapi-object), Bump.sh will use `Group by tags` as a default documentation generation behavior. ![](/images/help/operations.png) @@ -30,4 +30,4 @@ When group operation by tag is selected, Bump.sh will use the [`tags`](https://s Tags offer you better customization of your documentation, going beyond the resource names. You can also add a description for each tag, which will appear in the header of your documentation. > When "Group operations by tag" is selected, operations without tags will be ignored and won't be displayed. -{: .warning} \ No newline at end of file +{: .warning}