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.

Field	Type	Required	Description
`operationId`	String	✅	The `operationId` of an operation that exists in the document. Use either this field or the `operationRef` field, not both.
`operationRef`	String	✅	Either a Relative Reference or Absolute Reference to an operation that exists in the document. Use either this field or the `operationId` field, not both.
`description`	String		A description of the link and intentions for its use. This may contain CommonMark syntax (opens in a new tab) to provide a rich description.
`parameters`	Map[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`
`requestBody`	Any \| {Expression}		A constant value or Expression that will be used as the request body when calling the linked operation.
`server`	Server Object		An optional server to be used by the linked operation.
`x-*`	Extensions		Any 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