Streamline with references
In the previous topic, you completed your simple OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger.. While this file only had one operation A single request to a third-party API. Operations often become actions in the workflow designer. and one response The return from a third-party API after a request has been made by the client., most OpenAPI Specifications contain more, and it is helpful to define the data structures for parameters A piece of information passed to a third-party API during a request. and responses separately, so they can be used by more than one parameter or response.
Summary
Until now, you have written the object definitions for parameters and responses directly in the parameter or response object, by using the schema object. This means if you wanted to use the same object definition in several responses, you would need to copy and paste that definition into each response object.
References allow you to write the definition once in a special section of the OpenAPI Specification, and refer to it with a reference link every time you need it. It helps keep your OpenAPI Specification easy to read and maintain.
References and definitions in the OpenAPI Specification
Definitions in a OpenAPI Specification are stored in a special object that is usually at the end of the file, after the paths object. Each definition must have its own unique name within the OpenAPI Specification, and is referred to using the special $ref key, with the path to the definition as the value.
- Definitions for responses are stored in a definitions object.
- Definitions for parameters are stored in a parameters object.
Note: This is not the parameters array that exists within each HTTP method object, but a separate parameters object that is placed after the paths object.
Create a definition and reference
To create a definition and reference, you declare:
- The name of the definition
- The properties it contains
Then add the reference path to the schema of the objects that should use the definition.
Step 1: Create the definitions object
After the paths object, create the definitions object to hold the response definitions.
"definitions": {
}
Creating a parameters object to hold parameter definitions
After the paths object, create the parameters object to hold the parameter definitions.
Note: Unlike the parameters in the HTTP method object, this is an object, not an array. Make sure you use braces, not square brackets.
"parameters": {
}
Step 2: Create a definition object
Inside the definitions object, create an object to define the airport information received from the Airport-Data API. The key of the object is the name you give the definition. It must be unique within your definitions object.
"definitions": {
"airportInfo": {
}
}
If you want to create more than one definition, create a definition object for each definition and separate them with commas.
"definitions": {
"airportInfo": {
},
"airportDetails": {
}
}
Step 3: Define the object
Inside the definition object, add the data type of object, and a properties object to describe the information it contains. You can copy this directly from the original schema object in the response object.
"definitions": {
"airportInfo": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"location": {
"type": "string"
},
"country": {
"type": "string"
}
}
}
}
Step 4: Replace the original object with a reference
In the response object, replace the schema object properties with a key of $ref, and a value that is the path to the definition object.
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/airportInfo"
}
}
}
In the parameters array in the HTTP method object, replace the definition inside the parameter object with a key of $ref, and a value that is the path to the parameters definition object.
"parameters": [
{
"$ref": "#/parameters/myDefinition"
}
]
The OpenAPI Specification
The OpenAPI Specification is complete. You can import it for use in your workflows.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Airport Data",
"description": "Retrieves location information based on airport codes"
},
"host": "www.airport-data.com",
"basePath": "/api",
"schemes": [
"https"
],
"produces": [
"application/json"
],
"paths": {
"/ap_info.json": {
"get": {
"summary": "Get airport info",
"description": "Get airport info",
"operationId": "getAirportInfo",
"produces": [
"application/json"
],
"parameters": [
{
"name": "iata",
"description": "Airport code",
"in": "query",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/airportInfo"
}
}
}
}
}
},
"definitions": {
"airportInfo": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"location": {
"type": "string"
},
"country": {
"type": "string"
}
}
}
}
}