We encourage reuse and patterns through references.
The following types are reusable, as defined by the spec:
- Parameters
- Models (or Schema Objects in general)
- Responses
- Operations (Operations can only be remote references)
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".
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).
OpenAPI's provides reference capabilities using the JSON Reference specification.
{
// ...
definitions: {
Person: {
type: 'object',
properties: {
friends: {
type: 'array',
items: {
$ref: '#/definitions/Person'
}
}
}
}
}
}# ...
definitions:
Person:
type: object
properties:
friends:
type: array
items:
$ref: '#/definitions/Person'Note: YAML has a very similar feature, YAML anchors. Examples from this point will only be in JSON, using JSON References.
All references should follow the JSON Reference specification.
JSON Reference provides guidance on the resolution of references, notably:
If the URI contained in the JSON Reference value is a relative URI, then the base URI resolution MUST be calculated according to [RFC3986], section 5.2. Resolution is performed relative to the referring document.
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.
When referencing locally (within the current document), the target references should follow the conventions, as defined by the spec:
- Parameters ->
#/parameters - Responses ->
#/responses - Definitions (Models/Schema) ->
#/definitions
An example of a local definition reference:
Example from https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/json/petstore.json
// ...
"200": {
"description": "pet response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Pet"
}
}Files can be referred to in relative paths to the current document.
Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json
// ...
"responses": {
"default": {
"description": "unexpected error",
"schema": {
"$ref": "../common/Error.json"
}
}
}Remote references may also reference properties within the relative remote file.
Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json
// ...
"parameters": [
{
"$ref": "parameters.json#/tagsParam"
},
{
"$ref": "parameters.json#/limitsParam"
}
]Remote files can be hosted on an HTTP server (rather than the local file system).
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).
Assuming file https://my.company.com/definitions/Model.json
{
"description": "A simple model",
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"tag": {
"description": "A complex, shared property. Note the absolute reference",
"$ref": "https://my.company.com/definitions/Tag.json"
}
}
}Remote references may also reference properties within the remote file.
Assuming file https://my.company.com/definitions/models.json
{
"models": {
"Model": {
"description": "A simple model",
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"tag": {
"description": "a complex, shared property. Note the absolute reference",
"$ref": "https://my.company.com/definitions/models.json#/models/Tag"
}
}
},
"Tag": {
"description": "A tag entity in the system",
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
}
}
}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.
Refer to Guidelines for Referencing for referencing strategies.
Similar to model schemas, you can create a repository of parameters to describe the common entities that appear throughout a set of systems.
Refer to Guidelines for Referencing for referencing strategies.
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.
Assuming file https://my.company.com/parameters/parameters.json
{
"query" : {
"skip": {
"name": "skip",
"in": "query",
"description": "Results to skip when paginating through a result set",
"required": false,
"minimum": 0,
"type": "integer",
"format": "int32"
},
"limit": {
"name": "limit",
"in": "query",
"description": "Maximum number of results to return",
"required": false,
"minimum": 0,
"type": "integer",
"format": "int32"
}
}
}To include these parameters, you would need to add them individually as such:
{
"/pets": {
"get": {
"description": "Returns all pets from the system that the user has access to",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "A list of pets.",
"parameters" : [
{
"$ref": "https://my.company.com/parameters/parameters.json#/query/skip"
},
{
"$ref": "https://my.company.com/parameters/parameters.json#/query/limit"
},
{
"in": "query",
"name": "type",
"description": "the types of pet to return",
"required": false,
"type": "string"
}
],
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/pet"
}
}
}
}
}
}
}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:
Refer to Guidelines for Referencing for referencing strategies.
{
"/health": {
"$ref": "http://localhost:8000/operations.json#/health"
}
}Which points to the reference in the operations.json file:
{
"health": {
"get": {
"tags": [
"admin"
],
"summary": "Returns server health information",
"operationId": "getHealth",
"produces": [
"application/json"
],
"parameters": [],
"responses": {
"200": {
"description": "Health information from the server",
"schema": {
"$ref": "http://localhost:8000/models.json#/Health"
}
}
}
}
}
}Remember, you cannot override the definitions, but in this case, you can add additional operations on the same path level.
Refer to Guidelines for Referencing for referencing strategies.
Assume the file responses.json:
{
"NotFoundError": {
"description": "Entity not found",
"schema": {
"$ref": "#/definitions/ErrorModel"
}
}
}You can refer to it from a response definition:
{
"/pets/{petId}": {
"get": {
"tags": [
"pet"
],
"summary": "Returns server health information",
"operationId": "getHealth",
"produces": [
"application/json"
],
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID of pet to return",
"required": true,
"type": "integer",
"format": "int64"
}
],
"responses": {
"200": {
"description": "The pet",
"schema": {
"$ref": "#/definitions/Pet"
}
},
"400": {
"$ref": "http://localhost:8000/responses.json#/NotFoundError"
}
}
}
}
}