Skip to content

Commit 041569a

Browse files
ralfhandlralfhandl
authored
Merge branch 'main' into jekyll-4.4
2 parents cb39e66 + 600db85 commit 041569a

File tree

15 files changed

+887
-5
lines changed

15 files changed

+887
-5
lines changed

‎_config.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ title: OpenAPI Documentation
44
description: For API designers and writers wishing formalize their API in an OpenAPI Description document.
55
baseurl: /
66
logo: "/assets/images/OpenAPI_Logo_Pantone-1.png"
7-
footer_content: "\xA9 2023 OpenAPI Initiative. <a rel=\"license\" href=\"http://creativecommons.org/licenses/by/4.0/\"\
7+
image: "/assets/images/OpenAPI_Logo_Pantone-1.png"
8+
footer_content: "\xA9 2025 OpenAPI Initiative. <a rel=\"license\" href=\"http://creativecommons.org/licenses/by/4.0/\"\
89
><img alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by/4.0/80x15.png\"\
910
\ /></a><br />This work is licensed under a <a rel=\"license\" href=\"http://creativecommons.org/licenses/by/4.0/\"\
1011
>Creative Commons Attribution 4.0 International License</a>. The documentation is\

‎_includes/head_custom.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,11 @@
22
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-fork-ribbon-css/0.2.3/gh-fork-ribbon.min.css" />
33
<style>.github-fork-ribbon:before { background-color: #1d781d; }</style>
44
<a class="github-fork-ribbon" href="https://github.com/OAI/Documentation" data-ribbon="Fork me on GitHub" title="Fork me on GitHub">Fork me on GitHub</a>
5+
6+
{%- assign og_image = page.image | default: site.image -%}
7+
8+
<meta property="og:title" content="{{ page.title | default: site.title | escape }}" />
9+
<meta property="og:description" content="{{ page.excerpt | strip_html | truncate: 160 | default: site.description }}" />
10+
<meta property="og:image" content="{{ site.url }}{{ og_image }}" />
11+
<meta property="og:url" content="{{ page.url | absolute_url }}" />
12+
<meta property="og:type" content="website" />

‎examples/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Example API Descriptions
4-
nav_order: 6
4+
nav_order: 8
55
has_children: true
66
has_toc: true
77
---

‎overlay/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
layout: default
3-
nav_order: 8
3+
nav_order: 9
44
title: Overlays
55
has_children: true
66
has_toc: false

‎referencing/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Using References
4-
nav_order: 5
4+
nav_order: 7
55
has_children: true
66
has_toc: false
77
---

‎specification/http-methods.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
layout: default
3+
title: HTTP Methods
4+
parent: The OpenAPI Specification Explained
5+
nav_order: 10
6+
---
7+
8+
# HTTP Methods
9+
10+
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.
11+
12+
## Standard HTTP Methods (All Versions)
13+
14+
OpenAPI has always supported standard HTTP methods as operation keys in path items:
15+
16+
```yaml
17+
paths:
18+
/users:
19+
get: # Retrieve users
20+
summary: List users
21+
responses:
22+
'200':
23+
description: User list
24+
post: # Create user
25+
summary: Create a new user
26+
responses:
27+
'201':
28+
description: User created
29+
put: # Replace user collection
30+
summary: Replace all users
31+
delete: # Delete users
32+
summary: Delete all users
33+
options: # Get allowed methods
34+
summary: Get allowed methods for users endpoint
35+
head: # Get headers only
36+
summary: Get user list headers
37+
patch: # Update users
38+
summary: Update users
39+
trace: # Diagnostic trace
40+
summary: Trace users endpoint
41+
```
42+
43+
Each method corresponds to a specific HTTP verb and follows REST conventions for the expected behavior.
44+
45+
## Enhanced HTTP Method Support in OpenAPI 3.2
46+
47+
### QUERY Method Support
48+
{: .d-inline-block }
49+
OpenAPI 3.2+
50+
{: .label .label-green }
51+
52+
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.
53+
54+
### QUERY Method Example
55+
56+
```yaml
57+
# OpenAPI 3.2
58+
paths:
59+
/products:
60+
query:
61+
summary: Advanced product search
62+
requestBody:
63+
required: true
64+
content:
65+
application/json:
66+
schema:
67+
type: object
68+
properties:
69+
filter:
70+
type: object
71+
sort:
72+
type: array
73+
items:
74+
type: string
75+
responses:
76+
'200':
77+
description: Search results
78+
```
79+
80+
### Additional Operations for Custom Methods
81+
{: .d-inline-block }
82+
OpenAPI 3.2+
83+
{: .label .label-green }
84+
85+
Use `additionalOperations` for HTTP methods not covered by standard OpenAPI operations:
86+
87+
### Additional Operations Example
88+
89+
Add the method names in upper case, any supported HTTP method name can be used.
90+
91+
```yaml
92+
# OpenAPI 3.2
93+
paths:
94+
/documents/{id}:
95+
additionalOperations:
96+
LINK:
97+
summary: Link related documents
98+
parameters:
99+
- name: id
100+
in: path
101+
required: true
102+
schema: { type: string }
103+
requestBody:
104+
required: true
105+
content:
106+
application/json:
107+
schema:
108+
type: object
109+
properties:
110+
targetDocument:
111+
type: string
112+
relationship:
113+
type: string
114+
responses:
115+
'204':
116+
description: Link created successfully
117+
```
118+
119+
This approach makes it easier to adopt new methods as the HTTP landscape evolves.

‎specification/media-types.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
layout: default
3+
title: Sequential Media Types
4+
parent: The OpenAPI Specification Explained
5+
nav_order: 11
6+
---
7+
8+
# Sequential Media Types
9+
{: .d-inline-block }
10+
OpenAPI 3.2+
11+
{: .label .label-green }
12+
13+
OpenAPI 3.2 introduces support for sequential and streaming media types, enabling description of data streams where individual items arrive over time.
14+
15+
## New Schema Field: itemSchema
16+
17+
The key addition is the `itemSchema` field, which describes the structure of a repeated item in a response:
18+
19+
```yaml
20+
# OpenAPI 3.2
21+
responses:
22+
'200':
23+
description: Stream of updates
24+
content:
25+
text/event-stream:
26+
itemSchema:
27+
type: object
28+
properties:
29+
id: { type: string }
30+
data: { type: object }
31+
```
32+
33+
## Supported Sequential Media Types
34+
35+
OpenAPI 3.2 adds support for several streaming formats:
36+
37+
- **Server-Sent Events**: `text/event-stream`
38+
- **JSON Lines**: `application/jsonl`
39+
- **JSON Sequences**: `application/json-seq`
40+
- **Multipart Mixed**: `multipart/mixed`
41+
42+
## Enhanced Multipart Support
43+
44+
OpenAPI 3.2 introduces new encoding fields for multipart content:
45+
46+
### itemEncoding
47+
48+
Applies encoding to each item in a sequence:
49+
50+
```yaml
51+
# OpenAPI 3.2
52+
content:
53+
multipart/form-data:
54+
itemEncoding:
55+
file:
56+
contentType: application/octet-stream
57+
```
58+
59+
### prefixEncoding
60+
61+
Specifies encoding for items by position:
62+
63+
```yaml
64+
# OpenAPI 3.2
65+
content:
66+
multipart/mixed:
67+
prefixEncoding:
68+
- contentType: application/json
69+
- contentType: text/html
70+
```
71+
72+
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‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,8 +70,38 @@ Parameters can reside in different locations, indicated by the `in` field. The m
7070
in: query
7171
```
7272

73+
> **NOTE**:
74+
> If any parameters are `in: query`, then `in: querystring` cannot be used.
75+
76+
- `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:
77+
78+
```yaml
79+
paths:
80+
/search:
81+
get:
82+
parameters:
83+
- name: advancedQuery
84+
in: querystring
85+
content:
86+
application/x-www-form-urlencoded:
87+
schema:
88+
type: object
89+
properties:
90+
filters:
91+
type: object
92+
sorting:
93+
type: array
94+
items:
95+
type: string
96+
```
97+
98+
> **NOTE**:
99+
> `in: querystring` cannot be combined with `in:query`.
100+
73101
- `header`: The parameter is sent in a custom HTTP header as part of the request. Header names are **case-insensitive**.
74102

103+
- `cookie`: The parameter is sent in a Cookie header as part of the request.
104+
75105
### Parameter Type
76106

77107
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
97127

98128
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.
99129

130+
OpenAPI 3.2 adds the `cookie` style for more accurate cookie parameter descriptions:
131+
132+
```yaml
133+
# OpenAPI 3.2
134+
paths:
135+
/dashboard:
136+
get:
137+
parameters:
138+
- name: preferences
139+
in: cookie
140+
style: cookie # New in 3.2
141+
schema:
142+
type: object
143+
properties:
144+
theme: { type: string }
145+
language: { type: string }
146+
```
147+
100148
The tables given below exemplify the most common styles `simple`, `form`, `label`, and `matrix`:
101149

102150
- **Primitive types**: For example, an integer named `id` with value 1234.

‎specification/paths.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ paths:
3939
4040
## The Path Item Object
4141
42-
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).
42+
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.
4343

4444
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.
4545

‎specification/servers.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,33 @@ servers:
3030
description: Server located in Shenzhen
3131
```
3232
33+
## Enhanced Server Fields
34+
{: .d-inline-block }
35+
OpenAPI 3.2+
36+
{: .label .label-green }
37+
38+
OpenAPI 3.2 adds a `name` field to Server Objects for easier identification and reference:
39+
40+
```yaml
41+
servers:
42+
- name: Production
43+
url: https://api.example.com/v1
44+
description: Production server for live traffic
45+
- name: Staging
46+
url: https://staging-api.example.com/v1
47+
description: Staging environment for testing
48+
- name: Development
49+
url: http://localhost:3000/v1
50+
description: Local development server
51+
```
52+
53+
The `name` field is particularly useful for:
54+
- **Tool integration** - Development tools can reference servers by name
55+
- **Documentation clarity** - Clear identification in API documentation
56+
- **Environment switching** - Easy server selection in API clients
57+
- **Configuration management** - Named references in deployment scripts
58+
59+
3360
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:
3461

3562
```yaml

0 commit comments

Comments
 (0)