Using $ref to reuse code fragments in your OpenAPI files

If you deploy an API to an IBM® API Connect Management server by using the developer toolkit command line, you can use the $ref field in your OpenAPI YAML and JSON API definition files to reference a fragment of OpenAPI code that is defined in a separate file. When API Connect processes the source API definition file, the $ref field is replaced with the contents of the target file.

Use the following syntax in your source YAML file:

$ref: path_to_file_containing_code_fragment

Use the following syntax in your source JSON file:

{  
$ref: path_to_file_containing_code_fragment
}

For example:

$ref: code_fragments/my_fragment.yaml

{
  "$ref": "code_fragments/my_fragment.json"
}

The replacement of the $ref field with the target code fragment occurs when you perform any of the following actions on the API defined by the source API definition file:

Stage or publish an API to an API Connect Management server by using the apic publish command. For more information, see Publishing APIs and applications.
Validate the API definition YAML file by using the apic validate command. For more information, see Validating the YAML or JSON definition of an API or Product.

Important: You cannot insert a $ref field at the root level of your OpenAPI file.

Example 1

A source YAML file contains the following OpenAPI code:

swagger: '2.0'
info:
  version: 1.0.0
  title: Branches
  x-ibm-name: Branches
  description: Provides operations relating to BankA branch information.
basePath: /branches
paths:
  /details:
    get:
      responses:
        - $ref: code_fragments/paths.yaml#/details/get/responses
       .
       .
       .

The file paths.yaml contains the following OpenAPI code fragment:

details:
  get:
    responses:
      '200':
        description: 200 OK defined in $ref file
        schema:
          $ref: '#/definitions/branch'
    summary: Branch details
    description: Retrieve details of the current branches of BankA.

When API Connect processes the source YAML file, the $ref field is replaced with the target code fragment, yielding the following OpenAPI code:

swagger: '2.0'
info:
  version: 1.0.0
  title: Branches
  x-ibm-name: Branches
  description: Provides operations relating to BankA branch information.
basePath: /branches
paths:
  /details:
    get:
      responses:
        '200':
          description: 200 OK
          schema:
            $ref: '#/definitions/branch'
      summary: Branch details
      description: Retrieve details of the current branches of BankA.
       .
       .
       .

Example 2

Example of a reference to an external file that contains just the parameter details:

openapi: 3.0.0

info:
  version: 3.0.1
  title: BeamUp API
  x-ibm-name: BeamUpAPI
servers:
  - url: /
paths:
  /customers:
    get:
      parameters:
        - $ref: tests/fixtures/api/referenceFile.yaml
      responses:  
        200:
          description: An array of customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  customerID:
                    type: string
                  customerName:
                    type: string
.
.
.

The file referenceFile.yaml contains the following OpenAPI code fragment:

name: page
in: query
description: page of results to return
required: true
schema:
  type: integer

Example of a reference to an external file that contains the parameters inside a path code fragment:

openapi: 3.0.0

info:
  version: 3.0.1
  title: BeamUp API
  x-ibm-name: BeamUpAPI
servers:
  - url: /
paths:
  /customers:
    get:
      parameters:
        - $ref: tests/fixtures/api/referenceFileWithPath.yaml#/customers/get/parameters
      responses:  
        200:
          description: An array of customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  customerID:
                    type: string
                  customerName:
                    type: string

The file referenceFileWithPath.yaml contains the following OpenAPI code fragment:

customers:
  get:
    parameters:
      name: page
      in: query
      description: page of results to return
      required: true
      schema:
        type: integer