Using $ref to reuse code fragments in your OpenAPI (Swagger 2.0) 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 (Swagger 2.0) YAML and JSON API definition files to reference a fragment of OpenAPI (Swagger 2.0) code that is defined in a separate file. When IBM 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:

Push a draft API to an IBM API Connect Management server by using the apic drafts:push command. For more information, see Working with Drafts.
Stage or publish an API to an IBM 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 (Swagger 2.0) file.

Example

A source YAML file contains the following OpenAPI (Swagger 2.0) 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:
  $ref: ./code_fragments/paths.yaml
       .
       .
       .

The file paths.yaml contains the following OpenAPI (Swagger 2.0) 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 IBM API Connect processes the source YAML file, the $ref field is replaced with the target code fragment, yielding the following OpenAPI (Swagger 2.0) 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.
       .
       .
       .