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.
.
.
.