OpenAPI Links

The Links object is a map of Link Objects or References to Link Objects that allows for describing possible API-use scenarios between different operations. For example, if a response returns a Drink object, and the Drink object has an ingredients property that is a list of Ingredient objects, then a link can be defined to the listIngredients operation showing how the ingredients can be used as an input to the listIngredients operation.

For example:


/drink/{name}:
get:
operationId: getDrink
summary: Get a drink.
description: Get a drink by name, if authenticated this will include stock levels and product codes otherwise it will only include public information.
tags:
- drinks
parameters:
- name: name
in: path
required: true
schema:
type: string
responses:
responses:
"200":
description: A drink.
content:
application/json:
schema:
$ref: "#/components/schemas/Drink"
links:
listIngredients:
operationId: listIngredients
parameters:
ingredients: $response.body#/ingredients
description: The list of ingredients returned by the `getDrink` operation can be used as an input to the `listIngredients` operation, to retrieve additional details about the ingredients required to make the drink.
/ingredients:
get:
operationId: listIngredients
summary: Get a list of ingredients.
description: Get a list of ingredients, if authenticated this will include stock levels and product codes otherwise it will only include public information.
tags:
- ingredients
parameters:
- name: ingredients
in: query
description: A list of ingredients to filter by. If not provided all ingredients will be returned.
required: false
style: form
explode: false
schema:
type: array
items:
type: string
responses:
"200":
description: A list of ingredients.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Ingredient"
"5XX":
$ref: "#/components/responses/APIError"
default:
$ref: "#/components/responses/UnknownError"

Link Object in OpenAPI

The Link Object represents a possible link that can be followed from the response.

FieldTypeRequiredDescription
operationIdStringThe operationId of an operation that exists in the document. Use either this field or the operationRef field, not both.
operationRefStringEither a Relative Reference or Absolute Reference to an operation that exists in the document. Use either this field or the operationId field, not both.
descriptionStringA description of the link and intentions for its use. This may contain CommonMark syntax (opens in a new tab) to provide a rich description.
parametersMap[string, any | {Expression}]A map of parameters to pass to the linked operation. The key is the name of the parameter and the value is either a constant value or an Expression that will be evaluated.

The parameter name can also be qualified with the location of the parameter, for example, path.parameter_name or query.parameter_name
requestBodyAny | {Expression}A constant value or Expression that will be used as the request body when calling the linked operation.
serverServer ObjectAn optional server to be used by the linked operation.
x-*ExtensionsAny number of extension fields can be added to the link object that can be used by tooling and vendors.

An example of OperationRef:


links:
listIngredients:
operationRef: "#/paths/~1ingredients/get"
parameters:
ingredients: $response.body#/ingredients
# or
links:
listIngredients:
operationRef: "https://speakeasy.bar/#/paths/~1ingredients/get"
parameters:
ingredients: $response.body#/ingredients