Merge pull request #137 from lornajane/openapi3.2-resources

Prepare documentation additions for the 3.2 release

Author: lornajane

examples/index.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Example API Descriptions
-nav_order: 6
+nav_order: 8
 has_children: true
 has_toc: true
 ---

overlay/index.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-nav_order: 8
+nav_order: 9
 title: Overlays
 has_children: true
 has_toc: false

referencing/index.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Using References
-nav_order: 5
+nav_order: 7
 has_children: true
 has_toc: false
 ---

specification/http-methods.md

@@ -0,0 +1,119 @@
+---
+layout: default
+title: HTTP Methods
+parent: The OpenAPI Specification Explained
+nav_order: 10
+---
+
+# HTTP Methods
+
+OpenAPI supports describing operations using HTTP methods. This page covers the standard HTTP methods available in all OpenAPI versions, and the enhanced method support introduced in OpenAPI 3.2.
+
+## Standard HTTP Methods (All Versions)
+
+OpenAPI has always supported standard HTTP methods as operation keys in path items:
+
+```yaml
+paths:
+  /users:
+    get:      # Retrieve users
+      summary: List users
+      responses:
+        '200':
+          description: User list
+    post:     # Create user
+      summary: Create a new user
+      responses:
+        '201':
+          description: User created
+    put:      # Replace user collection
+      summary: Replace all users
+    delete:   # Delete users
+      summary: Delete all users
+    options:  # Get allowed methods
+      summary: Get allowed methods for users endpoint
+    head:     # Get headers only
+      summary: Get user list headers
+    patch:    # Update users
+      summary: Update users
+    trace:    # Diagnostic trace
+      summary: Trace users endpoint
+```
+
+Each method corresponds to a specific HTTP verb and follows REST conventions for the expected behavior.
+
+## Enhanced HTTP Method Support in OpenAPI 3.2
+
+### QUERY Method Support
+{: .d-inline-block }
+OpenAPI 3.2+
+{: .label .label-green }
+
+OpenAPI 3.2 adds native support for the [QUERY HTTP method](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-11.html), designed for complex queries that don't fit in URL query strings.
+
+### QUERY Method Example
+
+```yaml
+# OpenAPI 3.2
+paths:
+  /products:
+    query:
+      summary: Advanced product search
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                filter:
+                  type: object
+                sort:
+                  type: array
+                  items:
+                    type: string
+      responses:
+        '200':
+          description: Search results
+```
+
+### Additional Operations for Custom Methods
+{: .d-inline-block }
+OpenAPI 3.2+
+{: .label .label-green }
+
+Use `additionalOperations` for HTTP methods not covered by standard OpenAPI operations:
+
+### Additional Operations Example
+
+Add the method names in upper case, any supported HTTP method name can be used.
+
+```yaml
+# OpenAPI 3.2
+paths:
+  /documents/{id}:
+    additionalOperations:
+      LINK:
+        summary: Link related documents
+        parameters:
+          - name: id
+            in: path
+            required: true
+            schema: { type: string }
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  targetDocument:
+                    type: string
+                  relationship:
+                    type: string
+        responses:
+          '204':
+            description: Link created successfully
+```
+
+This approach makes it easier to adopt new methods as the HTTP landscape evolves.

specification/media-types.md

@@ -0,0 +1,72 @@
+---
+layout: default
+title: Sequential Media Types
+parent: The OpenAPI Specification Explained
+nav_order: 11
+---
+
+# Sequential Media Types
+{: .d-inline-block }
+OpenAPI 3.2+
+{: .label .label-green }
+
+OpenAPI 3.2 introduces support for sequential and streaming media types, enabling description of data streams where individual items arrive over time.
+
+## New Schema Field: itemSchema
+
+The key addition is the `itemSchema` field, which describes the structure of a repeated item in a response:
+
+```yaml
+# OpenAPI 3.2
+responses:
+  '200':
+    description: Stream of updates
+    content:
+      text/event-stream:
+        itemSchema:
+          type: object
+          properties:
+            id: { type: string }
+            data: { type: object }
+```
+
+## Supported Sequential Media Types
+
+OpenAPI 3.2 adds support for several streaming formats:
+
+- **Server-Sent Events**: `text/event-stream`
+- **JSON Lines**: `application/jsonl`
+- **JSON Sequences**: `application/json-seq`
+- **Multipart Mixed**: `multipart/mixed`
+
+## Enhanced Multipart Support
+
+OpenAPI 3.2 introduces new encoding fields for multipart content:
+
+### itemEncoding
+
+Applies encoding to each item in a sequence:
+
+```yaml
+# OpenAPI 3.2
+content:
+  multipart/form-data:
+    itemEncoding:
+      file:
+        contentType: application/octet-stream
+```
+
+### prefixEncoding
+
+Specifies encoding for items by position:
+
+```yaml
+# OpenAPI 3.2
+content:
+  multipart/mixed:
+    prefixEncoding:
+      - contentType: application/json
+      - contentType: text/html
+```
+
+Sequential media type support in OpenAPI 3.2 enables documentation of streaming and real-time APIs using the `itemSchema` field to describe individual items in data streams.

specification/parameters.md

@@ -70,8 +70,38 @@ Parameters can reside in different locations, indicated by the `in` field. The m
           in: query
   ```
 
+  > **NOTE**:
+  > If any parameters are `in: query`, then `in: querystring` cannot be used.
+
+- `querystring` (OpenAPI 3.2+): The entire query string is treated as a single parameter with complex structure, meaning 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
+  ```
+
+  > **NOTE**:
+  > `in: querystring` cannot be combined with `in:query`.
+
 - `header`: The parameter is sent in a custom HTTP header as part of the request. Header names are **case-insensitive**.
 
+- `cookie`: The parameter is sent in a Cookie header as part of the request.
+
 ### Parameter Type
 
 Most of the time a parameter's type can be specified by using a [Schema Object](https://spec.openapis.org/oas/v3.1.0#schemaObject) in the `schema` field. Schema objects allow defining primitive or complex types (like arrays or objects) and impose additional restrictions on them. For example:
@@ -97,6 +127,24 @@ In more advanced scenarios the `content` field can be used instead. It provides
 
 The `style` field describes how a parameter is to be serialized and its effect depends on the **type** of the parameter. The resulting matrix is therefore rather complex and can be consulted in the [Parameter Object](https://spec.openapis.org/oas/v3.1.0#style-examples) specification page.
 
+OpenAPI 3.2 adds the `cookie` style for more accurate cookie parameter descriptions:
+
+```yaml
+# OpenAPI 3.2
+paths:
+  /dashboard:
+    get:
+      parameters:
+        - name: preferences
+          in: cookie
+          style: cookie  # New in 3.2
+          schema:
+            type: object
+            properties:
+              theme: { type: string }
+              language: { type: string }
+```
+
 The tables given below exemplify the most common styles `simple`, `form`, `label`, and `matrix`:
 
 - **Primitive types**: For example, an integer named `id` with value 1234.

specification/paths.md

@@ -39,7 +39,7 @@ paths:
 
 ## The Path Item Object
 
-The [Path Item Object](https://spec.openapis.org/oas/v3.1.0#path-item-object) describes the HTTP operations that can be performed on a path with a separate [Operation Object](https://spec.openapis.org/oas/v3.1.0#operation-object) for each one. Allowed operations match HTTP method names like `get`, `put` or `delete`, to list the most common (find the complete list in the [Path Item Object](https://spec.openapis.org/oas/v3.1.0#path-item-object) specification).
+The [Path Item Object](https://spec.openapis.org/oas/v3.1.0#path-item-object) describes the HTTP operations that can be performed on a path with a separate [Operation Object](https://spec.openapis.org/oas/v3.1.0#operation-object) for each one. Allowed operations match HTTP method names like `get`, `put` or `delete`, to list the most common. For complete details about HTTP methods in OpenAPI, see the [HTTP Methods](http-methods) page.
 
 This object also accepts common properties for all operations on the path like `summary` or `description`. The details of each operation are given in each child Operation object.
 

specification/servers.md

@@ -30,6 +30,33 @@ servers:
   description: Server located in Shenzhen
 ```
 
+## Enhanced Server Fields
+{: .d-inline-block }
+OpenAPI 3.2+
+{: .label .label-green }
+
+OpenAPI 3.2 adds a `name` field to Server Objects for easier identification and reference:
+
+```yaml
+servers:
+- name: Production
+  url: https://api.example.com/v1
+  description: Production server for live traffic
+- name: Staging
+  url: https://staging-api.example.com/v1
+  description: Staging environment for testing
+- name: Development
+  url: http://localhost:3000/v1
+  description: Local development server
+```
+
+The `name` field is particularly useful for:
+- **Tool integration** - Development tools can reference servers by name
+- **Documentation clarity** - Clear identification in API documentation
+- **Environment switching** - Easy server selection in API clients
+- **Configuration management** - Named references in deployment scripts
+
+
 Individual API endpoints (as specified in the [Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object)) are then appended to this URL to construct the full endpoint URL. For example:
 
 ```yaml

specification/structure.md

@@ -80,6 +80,7 @@ The OAS structure is long and complex so this section just describes the minimal
 The root object in any OpenAPI Description is the [OpenAPI Object](https://spec.openapis.org/oas/v3.1.0#openapi-object), and only two of its fields are mandatory: `openapi` and `info`. Additionally, at least one of `paths`, `components` and `webhooks` is required.
 
 * `openapi` (**string**): This indicates the version of the OAS this OAD is using, e.g. "3.1.0". Using this field tools can check that the description correctly adheres to the specification.
+* `$self` (**string**, OpenAPI 3.2+): Provides the canonical URI for the document itself, used as the base URI for resolving relative references. This field is optional.
 * `info` ([Info Object](https://spec.openapis.org/oas/v3.1.0#info-object)): This provides general information about the API (like its description, author and contact information) but the only mandatory fields are `title` and `version`.
   * `title` (**string**): A human-readable name for the API, like "GitHub REST API", useful to keep API collections organized.
   * `version` (**string**): Indicates the version **of the API description** (not to be confused with the OAS version above). Tools can use this field to generate code that ensures that clients and servers are interacting through the same version of the API, for example.