You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We encourage reuse and patterns through references.
3
4
4
5
## What is reusable
6
+
5
7
The following types are reusable, as defined by the spec:
6
8
7
-
* Operations
8
9
* Parameters
10
+
* Models (_or Schema Objects in general_)
9
11
* Responses
10
-
*Models (or Schema Objects in general)
12
+
*Operations (_Operations can only be remote references_)
11
13
12
14
## Reuse strategy
13
-
When reusing components in an API design, a pointer is created from the definition to target design. The references are maintained in the structure, and can be updated by modifying the source definitions. This is different from a "copy on design" approach where references are injected into the design itself.
14
15
15
-
The reuse technique is transparent between JSON or YAML and is lossless when converting between the two.
16
+
When authoring API design documents, common object definitions can be utilized to avoid duplication. For example, imagine multiple path definitions that each share a common path parameter, or a common response structure. The OpenAPI specification allows reuse of common object definitions through the use of "references".
17
+
18
+
A reference is a construct in your API design document that indicates "the content for this portion of the document is defined elsewhere". To create a reference, at the location in your document where you want to reuse some other definition, create an object that has a `$ref` property whose value is a URI pointing to where the definition is (more on this in later sections).
19
+
20
+
OpenAPI's provides reference capabilities using the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) specification.
21
+
22
+
### JSON Example
23
+
24
+
```js
25
+
{
26
+
// ...
27
+
definitions: {
28
+
Person: {
29
+
type:'object',
30
+
properties: {
31
+
friends: {
32
+
type:'array',
33
+
items: {
34
+
$ref:'#/definitions/Person'
35
+
}
36
+
}
37
+
}
38
+
}
39
+
}
40
+
}
41
+
```
16
42
17
-
YAML anchors are technically allowed but break the general reuse strategy in Swagger, since anchors are "injected" into a single document. They are not recommended.
43
+
### YAML Example
44
+
45
+
```yaml
46
+
# ...
47
+
definitions:
48
+
Person:
49
+
type: object
50
+
properties:
51
+
friends:
52
+
type: array
53
+
items:
54
+
$ref: '#/definitions/Person'
55
+
```
18
56
19
-
Referenes can be made either inside the Swagger definition file or to external files. References are done using [JSON Reference](http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03).
57
+
Note: YAML has a very similar feature, [YAML anchors](http://yaml.org/spec/1.2/spec.html#id2765878). Examples from this point will only be in JSON, using JSON References.
20
58
21
59
## Techniques
22
60
23
61
### Guidelines for Referencing
24
62
25
-
When referencing internally, the target references have designated locations:
63
+
All references should follow the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) specification.
26
64
27
-
* Parameters -> `parameters`
28
-
* Responses -> `responses`
29
-
* Models (and general Schema Objects) -> `definitions`
65
+
JSON Reference provides guidance on the resolution of references, notably:
30
66
31
-
Operations can only be referenced externally.
67
+
> If the URI contained in the JSON Reference value is a relative URI,
68
+
then the base URI resolution MUST be calculated according to
69
+
[RFC3986], section 5.2. Resolution is performed relative to the
70
+
referring document.
32
71
33
-
An example for an internal reference - `#/definitions/MyModel`. All references are canonical and must be a qualified [JSON Pointer](http://tools.ietf.org/html/rfc6901). For example, simply referencing `MyModel` is not allowed, even if there are no other definitions of it in the file.
72
+
Whether you reference definitions locally or remote, you can never override or change their definitions from the referring location. The definitions can only be used as-is.
34
73
35
-
When referencing externally, use a valid URI as the reference value. If your referenced file contains only one definition that should be used, you can refer to the file directly. For example:
Files can be referred to in relative paths to the current document.
102
+
103
+
_Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_
104
+
105
+
``` json
106
+
// ...
107
+
"responses": {
108
+
"default": {
109
+
"description": "unexpected error",
110
+
"schema": {
111
+
"$ref": "../common/Error.json"
112
+
}
113
+
}
74
114
}
75
115
```
76
116
77
-
The reference to the `Model` model would be `https://my.company.com/definitions/models.json#/models/Model`. Make sure you include the full path to the model itself, including its containers if needed.
117
+
Remote references may also reference properties within the relative remote file.
118
+
119
+
_Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_
120
+
``` json
121
+
// ...
122
+
"parameters": [
123
+
{
124
+
"$ref": "parameters.json#/tagsParam"
125
+
},
126
+
{
127
+
"$ref": "parameters.json#/limitsParam"
128
+
}
129
+
]
130
+
```
78
131
79
-
Whether you reference definitions internally or externally, you can never override or change their definitions from the referring location. The definitions can only be used as-is.
80
132
81
-
### Definitions
82
-
Reuse schema definitions by creating a repository of definitions. This is done by simply hosting a file or set of files for commonly used definitions across a company or organization. In the case of multiple files, the models can be referenced directly as such:
133
+
##### URL
134
+
135
+
Remote files can be hosted on an HTTP server (rather than the local file system).
136
+
137
+
One risk of this approach is that environment specific issues could arise if DNS is not taken into account (as the reference can only contain one hostname).
Reuse schema definitions by creating a repository of definitions. This is done by simply hosting a file or set of files for commonly used definitions across a company or organization.
194
+
195
+
Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies.
196
+
197
+
136
198
### Parameters
137
-
Similar to model schemas, you can create a repository of `parameters` to describe the common entities that appear throughout a set of systems. Using the same technique as above, you can host on either a single or multiple files. For simplicity, the example below assumes a single file.
199
+
200
+
Similar to model schemas, you can create a repository of `parameters` to describe the common entities that appear throughout a set of systems.
201
+
202
+
Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies.
203
+
204
+
Using the same technique as above, you can host on either a single or multiple files. For simplicity, the example below assumes a single file.
@@ -205,7 +272,10 @@ To include these parameters, you would need to add them individually as such:
205
272
```
206
273
207
274
### Operations
208
-
Again, Operations can be shared across files. Although the reusability of operations will be less than with Parameters and models. For this example, we will share a common `health` resource so that all APIs can reference it:
275
+
276
+
Again, Operations can be shared across files. Although the reusability of operations will be less than with Parameters and Definitions. For this example, we will share a common `health` resource so that all APIs can reference it:
277
+
278
+
Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies.
209
279
210
280
```json
211
281
{
@@ -246,7 +316,8 @@ Which points to the reference in the `operations.json` file:
246
316
Remember, you cannot override the definitions, but in this case, you can add additional operations on the same path level.
247
317
248
318
### Responses
249
-
Just like the other objects, responses can be reused as well.
319
+
320
+
Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies.
250
321
251
322
Assume the file `responses.json`:
252
323
@@ -299,6 +370,3 @@ You can refer to it from a response definition:
299
370
}
300
371
}
301
372
```
302
-
303
-
### Constraints
304
-
* Referenced objects must be to JSON structures. YAML reuse structures may be supported in a future version.
0 commit comments