Skip to content

Commit b86ac22

Browse files
beezythebotbeezythebot
committed
Sync open source content 🐝 (from 14072d378cae3f817ebb588e21e78262f3c6aaf2)
1 parent 1f1d16c commit b86ac22

File tree

6 files changed

+240
-17
lines changed

6 files changed

+240
-17
lines changed

‎openapi/content/jsonl.mdx‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ title: "Jsonl in OpenAPI best practices"
33
description: "Comprehensive guide to Jsonl in OpenAPI. Best practices for API design, documentation, and implementation."
44
---
55

6+
import { Callout } from "@/mdx/components";
7+
68
# JSONL responses in OpenAPI
79

810
JSON Lines (JSONL) is a convenient format for storing structured data that may be processed one record at a time. It's a simple format where each line is a valid JSON value, typically a JSON object or array. JSONL is particularly useful for handling large datasets, streaming data, or log files where each line represents a separate record.
@@ -28,8 +30,13 @@ JSONL offers several advantages over traditional JSON:
2830

2931
## Defining JSONL responses in OpenAPI documents
3032

31-
JSONL responses can be defined in OpenAPI by using the `application/jsonl` or `text/jsonl` MIME type. While JSONL isn't natively supported in the OpenAPI specification, you can use these content types to indicate that the response will be in JSONL format.
32-
Here's an example of how to define a JSONL response in an OpenAPI document:
33+
<Callout title="OpenAPI v3.2.0 JSONL support" type="info">
34+
OpenAPI v3.2.0 recognizes `application/jsonl` as a sequential media type and introduces the `itemSchema` keyword for defining the structure of individual records in the stream.
35+
</Callout>
36+
37+
JSONL responses can be defined in OpenAPI by using the `application/jsonl` or `text/jsonl` MIME type. In OpenAPI v3.0 and v3.1, JSONL isn't natively supported, but these content types indicate that the response will be in JSONL format. OpenAPI v3.2.0 adds native support through the `itemSchema` keyword, which defines the schema for each line in the JSONL stream.
38+
39+
The following example defines a JSONL response in an OpenAPI document:
3340

3441
```yaml filename="openapi.yaml"
3542
paths:
@@ -79,6 +86,28 @@ components:
7986
8087
In this example, the `/users/export` endpoint returns user data in JSONL format. Each line of the response will be a valid JSON object representing a user, as defined by the `User` schema.
8188

89+
### Using itemSchema in OpenAPI 3.2
90+
91+
With OpenAPI v3.2.0, the `itemSchema` keyword explicitly defines the schema for each line in the JSONL stream:
92+
93+
```yaml filename="openapi.yaml"
94+
paths:
95+
/users/export:
96+
get:
97+
summary: Export user data in JSONL format
98+
responses:
99+
"200":
100+
description: User data in JSONL format
101+
content:
102+
application/jsonl:
103+
schema:
104+
type: string
105+
itemSchema:
106+
$ref: "#/components/schemas/User"
107+
```
108+
109+
The `schema` describes the overall stream, while `itemSchema` defines the structure of each individual JSON object per line. This allows tooling to generate typed deserialization for each record in the stream.
110+
82111
## Client-side handling of JSONL responses
83112

84113
When working with JSONL responses, clients need to process the data line by line. Here's an example of how to handle JSONL responses using a python SDK generated by Speakeasy:

‎openapi/content/server-sent-events.mdx‎

Lines changed: 42 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: "Server Sent Events in OpenAPI best practices"
33
description: "Comprehensive guide to Server Sent Events in OpenAPI. Best practices for API design, documentation, and implementation."
44
---
55

6-
import { Table } from "@/mdx/components";
6+
import { Callout, Table } from "@/mdx/components";
77

88
# Server-sent events in OpenAPI
99

@@ -65,7 +65,11 @@ SSE is ideal for simple, efficient, one-way server-to-client communication scena
6565

6666
## Defining SSE in OpenAPI documents
6767

68-
Server-sent events (SSE) are not natively supported in OpenAPI but can be represented as an endpoint using the `text/event-stream` MIME type to indicate the data format.
68+
<Callout title="OpenAPI v3.2.0 SSE support" type="info">
69+
OpenAPI v3.2.0 introduces the `itemSchema` keyword for `text/event-stream` media types, providing first-class support for defining the structure of individual streamed events. See the [itemSchema section](#defining-sse-with-itemschema-in-openapi-32) below.
70+
</Callout>
71+
72+
In OpenAPI v3.0 and v3.1, server-sent events (SSE) are not natively supported but can be represented as an endpoint using the `text/event-stream` MIME type to indicate the data format. OpenAPI v3.2.0 adds first-class support for SSE with the `itemSchema` keyword.
6973

7074
The event stream format is a UTF-8-encoded text stream with messages separated by a newline (`\n`). Each message may include up to four fields:
7175

@@ -147,6 +151,42 @@ eventSource.onerror = function (error) {
147151
};
148152
```
149153

154+
## Defining SSE with itemSchema in OpenAPI 3.2
155+
156+
OpenAPI v3.2.0 introduces the `itemSchema` keyword, which defines the schema for individual events within a `text/event-stream` response. Instead of describing the entire stream as one schema, `itemSchema` describes the structure of each event delivered over the stream.
157+
158+
```yaml filename="openapi.yaml"
159+
paths:
160+
/stock-updates:
161+
get:
162+
tags:
163+
- ServerSentEvents
164+
summary: Subscribe to real-time stock market updates
165+
responses:
166+
"200":
167+
description: Stream of real-time stock updates
168+
content:
169+
text/event-stream:
170+
schema:
171+
type: string
172+
itemSchema:
173+
$ref: "#/components/schemas/StockUpdate"
174+
components:
175+
schemas:
176+
StockUpdate:
177+
type: object
178+
properties:
179+
symbol:
180+
type: string
181+
description: Stock ticker symbol
182+
price:
183+
type: string
184+
description: Current stock price
185+
example: "100.25"
186+
```
187+
188+
In this example, the `schema` describes the overall stream as a string (the raw event stream), while `itemSchema` defines the structure of each individual event within the stream. This separation allows tooling to generate typed handlers for each event.
189+
150190
## Best practices for SSE design and OpenAPI integration
151191

152192
Here are some best practices for handling server-sent events and including them in an OpenAPI document.

‎openapi/operations.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import { Table } from "@/mdx/components";
88

99
An operation object describes a single API operation within a path, including all its possible inputs and outputs and the configuration required to make a successful request.
1010

11-
Each operation object corresponds to an HTTP verb, such as `get`, `post`, or `delete`.
11+
Each operation object corresponds to an HTTP method, such as `get`, `post`, `delete`, or `query` (introduced in OpenAPI v3.2.0).
1212

1313
Example:
1414

@@ -133,3 +133,5 @@ paths:
133133
/>
134134

135135
The above order of fields is recommended for defining the fields in the document to help set the stage for the operation and provide a clear understanding of what it does.
136+
137+
OpenAPI v3.2.0 also introduces the [`query` method and `additionalOperations`](/openapi/paths#openapi-32-path-features) for defining the `QUERY` HTTP method and non-standard HTTP methods as Operation Objects.

‎openapi/paths.mdx‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,8 @@ components:
111111
{ field: "`head`", type: "[Operation Object](/openapi/paths/operations)", required: "", description: "An operation associated with the [`HEAD` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD)." },
112112
{ field: "`patch`", type: "[Operation Object](/openapi/paths/operations)", required: "", description: "An operation associated with the [`PATCH` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH)." },
113113
{ field: "`trace`", type: "[Operation Object](/openapi/paths/operations)", required: "", description: "An operation associated with the [`TRACE` HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/TRACE)." },
114+
{ field: "`query`", type: "[Operation Object](/openapi/paths/operations)", required: "", description: "An operation associated with the `QUERY` HTTP method. Safe and idempotent, like `GET`, but allows a request body for complex queries. Available in OpenAPI v3.2.0+." },
115+
{ field: "`additionalOperations`", type: "Map[String, [Operation Object](/openapi/paths/operations)]", required: "", description: "A map of non-standard HTTP methods to Operation Objects, enabling documentation of custom methods beyond those defined by the specification. Available in OpenAPI v3.2.0+." },
114116
{ field: "`x-*`", type: "[Extensions](/openapi/extensions)", required: "", description: "Any number of extension fields can be added to the Path Item Object that can be used by tooling and vendors." }
115117
]}
116118
columns={[
@@ -122,3 +124,90 @@ components:
122124
/>
123125

124126
The order of fields above is recommended but is not significant to the order in which the endpoints should be used.
127+
128+
## OpenAPI 3.2 path features
129+
130+
OpenAPI 3.2.0 introduces several new capabilities for path items.
131+
132+
### The QUERY HTTP method
133+
134+
The `QUERY` method is a safe, idempotent HTTP method that allows clients to send query criteria in the request body rather than encoding complex parameters in the URL. This is useful for operations that require structured or lengthy query parameters that exceed practical URL length limits.
135+
136+
```yaml
137+
paths:
138+
/drinks:
139+
query:
140+
operationId: searchDrinks
141+
summary: Search for drinks with complex criteria
142+
requestBody:
143+
required: true
144+
content:
145+
application/json:
146+
schema:
147+
type: object
148+
properties:
149+
ingredients:
150+
type: array
151+
items:
152+
type: string
153+
minRating:
154+
type: number
155+
responses:
156+
"200":
157+
description: A list of matching drinks
158+
content:
159+
application/json:
160+
schema:
161+
type: array
162+
items:
163+
$ref: "#/components/schemas/Drink"
164+
```
165+
166+
### Additional operations
167+
168+
The `additionalOperations` field allows defining non-standard HTTP methods as Operation Objects. This is useful for APIs that use custom HTTP methods beyond the standard set.
169+
170+
```yaml
171+
paths:
172+
/drinks/{drinkId}:
173+
additionalOperations:
174+
BREW:
175+
operationId: brewDrink
176+
summary: Brew a specific drink
177+
parameters:
178+
- name: drinkId
179+
in: path
180+
required: true
181+
schema:
182+
type: string
183+
responses:
184+
"200":
185+
description: Drink brewed successfully
186+
```
187+
188+
### The querystring field
189+
190+
OpenAPI 3.2.0 also introduces the `querystring` field on Operation Objects, which allows defining all query parameters as a single Schema Object instead of listing individual `parameters` with `in: query`. This simplifies the definition of operations with many query parameters or complex query structures.
191+
192+
```yaml
193+
paths:
194+
/drinks:
195+
get:
196+
operationId: listDrinks
197+
summary: List available drinks
198+
querystring:
199+
type: object
200+
properties:
201+
type:
202+
type: string
203+
enum: [cocktail, mocktail, spirit, beer, wine, cider]
204+
limit:
205+
type: integer
206+
default: 20
207+
offset:
208+
type: integer
209+
default: 0
210+
responses:
211+
"200":
212+
description: A list of drinks
213+
```

‎openapi/security/security-schemes/security-oauth2.mdx‎

Lines changed: 61 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ The fields for an OAuth 2 security scheme are as follows:
2222
data={[
2323
{ field: "`type`", type: "String", required: "✅", description: "`oauth2`" },
2424
{ field: "`description`", type: "String", required: "", description: "Human-readable information. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description." },
25-
{ field: "`flows`", type: "Map[{key}, [OAuth Flow Object](#oauth-flow-object)]", required: "✅", description: "An object containing configuration for the available OAuth 2 flows. Valid keys are `implicit`, `password`, `clientCredentials`, and `authorizationCode`." },
25+
{ field: "`flows`", type: "Map[{key}, [OAuth Flow Object](#oauth-flow-object)]", required: "✅", description: "An object containing configuration for the available OAuth 2 flows. Valid keys are `implicit`, `password`, `clientCredentials`, `authorizationCode`, and `deviceAuthorization` (OpenAPI v3.2.0+)." },
2626
{ field: "`x-*`", type: "[Extensions](/openapi/extensions)", required: "", description: "Any number of extension fields can be added to the Security Scheme Object to be used by tooling and vendors." }
2727
]}
2828
columns={[
@@ -52,12 +52,13 @@ security:
5252
5353
The value of the [OAuth Flows Object](https://spec.openapis.org/oas/v3.1.0#oauth-flows-object) is a map of [OAuth Flow Objects](https://spec.openapis.org/oas/v3.1.0#oauth-flow-object).
5454
55-
The OpenAPI Specification 3.1 supports the following four OAuth Flow Objects:
55+
The OpenAPI Specification supports the following OAuth Flow Objects:
5656
5757
- The [Client Credentials](#the-client-credentials-flow) flow (using `clientCredentials`, previously `application` in OpenAPI 2.0)
5858
- The [Authorization Code](#the-authorization-code-flow) flow (using `authorizationCode`, previously `accessCode` in OpenAPI 2.0)
5959
- The [Password](#the-password-flow) flow (using `password`)
6060
- The [Implicit](#the-implicit-flow) flow (using `implicit`)
61+
- The [Device Authorization](#the-device-authorization-flow) flow (using `deviceAuthorization`, available in OpenAPI v3.2.0+)
6162

6263
Each OAuth Flow Object has its own configuration parameters, so let's look at them individually.
6364

@@ -346,6 +347,62 @@ OAuth 2.1 is a simplified version of OAuth 2 that combines its best practices an
346347

347348
For more information on the changes and improvements made in OAuth 2.1, refer to [the OAuth 2.1 specification](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13).
348349

349-
**Device Authorization** is a new OAuth flow (also called a grant) that is not yet supported in the OpenAPI Specification 3.1. It will be added in the OpenAPI Specification 3.2, which is currently in development.
350+
### The Device Authorization flow
350351

351-
For more information on the Device Authorization grant, take a look at the specification for the [OAuth 2.0 Device Authorization grant](https://datatracker.ietf.org/doc/html/rfc8628).
352+
The Device Authorization flow (also called the Device Authorization grant) is designed for devices with limited input capabilities, such as smart TVs, kiosks, and IoT devices. Instead of entering credentials directly, the device displays a code that the user enters on a separate device with a full browser. OpenAPI v3.2.0 adds support for this flow using the `deviceAuthorization` key.
353+
354+
For more information on the Device Authorization grant, refer to the specification for the [OAuth 2.0 Device Authorization grant](https://datatracker.ietf.org/doc/html/rfc8628).
355+
356+
<Table
357+
data={[
358+
{ field: "`deviceAuthorizationUrl`", type: "String", required: "✅", description: "The device authorization URL to be used for this flow." },
359+
{ field: "`tokenUrl`", type: "String", required: "✅", description: "The token URL to be used for this flow." },
360+
{ field: "`refreshUrl`", type: "String", required: "", description: "The URL to be used for refreshing the token. No refresh URL means the token is not refreshable." },
361+
{ field: "`scopes`", type: "Map[String, String]", required: "✅", description: "The available scopes for the OAuth 2 flow, with a description for each scope. Although the specification requires this field, it can be an empty object." },
362+
{ field: "`x-*`", type: "[Extensions](/openapi/extensions)", required: "", description: "Any number of extension fields can be added to an OAuth Flow Object to be used by tooling and vendors to add additional metadata and functionality to the OpenAPI Specification." }
363+
]}
364+
columns={[
365+
{ key: "field", header: "Field" },
366+
{ key: "type", header: "Type" },
367+
{ key: "required", header: "Required" },
368+
{ key: "description", header: "Description" }
369+
]}
370+
/>
371+
372+
The following example shows an OAuth 2 security scheme using the `deviceAuthorization` flow:
373+
374+
```yaml
375+
components:
376+
securitySchemes:
377+
deviceAuth:
378+
type: oauth2
379+
flows:
380+
deviceAuthorization:
381+
deviceAuthorizationUrl: https://speakeasy.bar/oauth2/device
382+
tokenUrl: https://speakeasy.bar/oauth2/token
383+
refreshUrl: https://speakeasy.bar/oauth2/refresh
384+
scopes:
385+
read: Grants read access
386+
write: Grants write access
387+
security:
388+
- deviceAuth: []
389+
```
390+
391+
## OAuth 2.0 metadata discovery
392+
393+
OpenAPI v3.2.0 adds the `oauth2MetadataUrl` field to the OAuth Flow Object. This field provides a URL pointing to the OAuth 2.0 Authorization Server Metadata document ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)), enabling clients to automatically discover OAuth 2.0 endpoint configuration.
394+
395+
```yaml
396+
components:
397+
securitySchemes:
398+
oauth2:
399+
type: oauth2
400+
flows:
401+
authorizationCode:
402+
authorizationUrl: https://speakeasy.bar/oauth2/authorize
403+
tokenUrl: https://speakeasy.bar/oauth2/token
404+
oauth2MetadataUrl: https://speakeasy.bar/.well-known/oauth-authorization-server
405+
scopes:
406+
read: Grants read access
407+
write: Grants write access
408+
```

0 commit comments

Comments
 (0)