Skip to content

Commit 772d66d

Browse files
philsturgeonchailandau
philsturgeon
and
chailandau
authored
[PMM-291] OpenAPI: Components (#28)
Co-authored-by: Chai Landau <112015853+chailandau@users.noreply.github.com>
1 parent ef3afb8 commit 772d66d

2 files changed

Lines changed: 118 additions & 25 deletions

File tree

‎docs/speakeasy-reference/cli/merge.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
1-
# merge
1+
# merge
22
`speakeasy merge`
33

4-
5-
Merge multiple OpenAPI documents into a single document
4+
Merge multiple OpenAPI documents into a single document.
65

76
## Details
87

9-
Merge multiple OpenAPI documents into a single document, useful for merging multiple OpenAPI documents into a single document for generating a client SDK.
10-
Note: That any duplicate operations, components, etc. will be overwritten by the next document in the list.
8+
Merging multiple OpenAPI documents together allows for multiple teams or departments to control their own API endpoints, and merge the end result later. Or one document for API endpoints, and another document for webhooks, with the end goal being getting it into one OpenAPI document to make it more portable.
9+
10+
This is a bit different to "bundling" or "dereferencing", which is about pulling external references into the main document.
11+
12+
**Note:** Any duplicate operations, components, etc. will be overwritten by the next document in the list.
1113

1214
## Usage
1315

‎openapi/components.mdx‎

Lines changed: 111 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,178 @@
11
---
22
title: "Components in OpenAPI best practices"
3-
description: "Master the Components Object in OpenAPI to efficiently reuse schema definitions, parameters, responses, and more across your API specification."
3+
description: "Master the Components Object in OpenAPI to efficiently reuse schema definitions, parameters, responses, and more across API descriptions."
44
---
55

6-
# Components Object in OpenAPI
6+
# Components in OpenAPI
77

88
import { Table } from "@/mdx/components";
99

10-
The Components Object is a container for reusable objects that can be referenced across the API. These objects can be referenced using [References](/openapi/references), and generally are only valid if referenced by other parts of the API.
10+
The Components object in OpenAPI are reusable bits of OpenAPI description, which
11+
can then be [referenced](/openapi/references). Reusing components allows for
12+
smaller file-sizes, reduces conflicts, and improves consistency across the API.
13+
Components can even be shared them across multiple documents, allowing for
14+
improved reuse between multiple APIs.
15+
16+
```yaml
17+
components:
18+
schemas:
19+
User:
20+
type: object
21+
properties:
22+
id:
23+
type: integer
24+
name:
25+
type: string
26+
email:
27+
type: string
28+
format: email
29+
parameters:
30+
userId:
31+
name: uuid
32+
in: path
33+
description: Unique UUIDv4 of the user
34+
required: true
35+
schema:
36+
type: string
37+
format: uuid
38+
responses:
39+
NotFound:
40+
description: User not found
41+
content:
42+
application/json:
43+
schema:
44+
$ref: '#/components/schemas/Error'
45+
requestBodies:
46+
User:
47+
content:
48+
application/json:
49+
schema:
50+
$ref: '#/components/schemas/User'
51+
securitySchemes:
52+
bearerAuth:
53+
type: http
54+
scheme: bearer
55+
bearerFormat: JWT
56+
```
57+
58+
Components can be referenced in other parts of the OpenAPI document using the
59+
`$ref` keyword. The `$ref` keyword is a JSON Pointer to the component, which
60+
is a string that starts with `#/components/` and then the component type
61+
and name. For example, to reference the `User` schema defined in the
62+
Components Object, you would use the following `$ref`:
63+
64+
```yaml
65+
responses:
66+
'200':
67+
description: User found
68+
content:
69+
application/json:
70+
schema:
71+
$ref: '#/components/schemas/User'
72+
```
73+
74+
To put it all together, here is an example of how to reference all the various components in that previous example:
75+
76+
```yaml
77+
paths:
78+
/users/{userId}:
79+
get:
80+
summary: Get a user by UUID
81+
parameters:
82+
- $ref: '#/components/parameters/userId'
83+
responses:
84+
'200':
85+
description: User found
86+
content:
87+
application/json:
88+
schema:
89+
$ref: '#/components/schemas/User'
90+
'404':
91+
$ref: '#/components/responses/NotFound'
92+
security:
93+
- bearerAuth: []
94+
```
95+
96+
## Components Object
97+
98+
The Components Object is a map of reusable components broken down by type.
99+
100+
```yaml
101+
components:
102+
<componentType>:
103+
<componentName>:
104+
<componentDefinition>
105+
```
106+
107+
The component name can be any valid string, but it is recommended to use a
108+
consistent naming convention across the API. A common naming convention is `PascalCase` or `camelCase`.
109+
110+
```yaml
111+
components:
112+
schemas:
113+
Train:
114+
Station:
115+
BookingPayments:
116+
```
117+
118+
Here are the supported component types as of OpenAPI v3.1:
11119

12120
<Table
13121
data={[
14122
{
15123
field: "`schemas`",
16124
type: "Map[string, [Schema Object](/openapi/schemas)]*",
17-
required: "",
18125
description: "A map of [Schema Objects](/openapi/schemas) that can be referenced by other parts of the API.\n\n**Note: OpenAPI 3.0.x does support [OpenAPI Reference Objects](/openapi/references#openapi-reference-object) as the value here, but `3.1.x` uses the [JSON Schema Referencing](/openapi/schemas#json-schema--openapi) format.**"
19126
},
20127
{
21128
field: "`securitySchemes`",
22129
type: "Map[string, [Security Scheme Object](/openapi/security/security-schemes) \\| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]*",
23-
required: "",
24130
description: "A map of [Security Scheme Objects](/openapi/security/security-schemes) that can be referenced by other parts of the API."
25131
},
26132
{
27133
field: "`pathItems`",
28134
type: "Map[string, [Path Item Object](/openapi/paths#path-item-object) \\| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]*",
29-
required: "",
30135
description: "A map of [Path Item Objects](/openapi/paths#path-item-object) that can be referenced by other parts of the API."
31136
},
32137
{
33138
field: "`parameters`",
34139
type: "Map[string, [Parameter Object](/openapi/paths/parameters#parameter-object) \\| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]*",
35-
required: "",
36140
description: "A map of [Parameter Objects](/openapi/paths/parameters#parameter-object) that can be referenced by other parts of the API."
37141
},
38142
{
39143
field: "`requestBodies`",
40144
type: "Map[string, [Request Body Object](/openapi/paths/operations/requests) \\| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]*",
41-
required: "",
42145
description: "A map of [Request Body Objects](/openapi/paths/operations/requests) that can be referenced by other parts of the API."
43146
},
44147
{
45148
field: "`responses`",
46149
type: "Map[string, [Response Object](/openapi/paths/operations/responses#response-object) \\| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]*",
47-
required: "",
48150
description: "A map of [Response Objects](/openapi/paths/operations/responses#response-object) that can be referenced by other parts of the API."
49151
},
50152
{
51153
field: "`headers`",
52154
type: "Map[string, [Header Object](/openapi/paths/operations/responses/headers) \\| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]*",
53-
required: "",
54155
description: "A map of [Header Objects](/openapi/paths/operations/responses/headers) that can be referenced by other parts of the API."
55156
},
56157
{
57158
field: "`examples`",
58159
type: "Map[string, [Example Object](/openapi/examples) \\| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]*",
59-
required: "",
60160
description: "A map of [Example Objects](/openapi/examples) that can be referenced by other parts of the API."
61161
},
62162
{
63163
field: "`callbacks`",
64164
type: "Map[string, [Callback Object](/openapi/paths/operations/callbacks#callback-object) \\| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]*",
65-
required: "",
66165
description: "A map of [Callback Objects](/openapi/paths/operations/callbacks#callback-object) that can be referenced by other parts of the API."
67166
},
68167
{
69168
field: "`links`",
70169
type: "Map[string, [Link Object](/openapi/paths/operations/responses/links#link-object) \\| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)]*",
71-
required: "",
72170
description: "A map of [Link Objects](/openapi/paths/operations/responses/links#link-object) that can be referenced by other parts of the API."
73-
},
74-
{
75-
field: "`x-*`",
76-
type: "[Extensions](/openapi/extensions)",
77-
required: "",
78-
description: "Any number of extension fields can be added to the Components Object that can be used by tooling and vendors."
79171
}
80172
]}
81173
columns={[
82174
{ key: "field", header: "Field" },
83175
{ key: "type", header: "Type" },
84-
{ key: "required", header: "Required" },
85176
{ key: "description", header: "Description" }
86177
]}
87178
/>

0 commit comments

Comments
 (0)