Referring to an extension in an API definition

To refer to an OpenAPI extension in your API definition YAML (or JSON) file, add an extensions key under x-ibm-configuration.

Before you begin

Add the OpenAPI extension to any Catalogs that the API is to be published to, by importing its definition file; for details, see Working with OpenAPI extensions. If the target Catalog does not contain the OpenAPI extension then attempts to publish the API to it will fail.

About this task

The following example shows an extension definition file that defines a bank branch, in YAML format:

extension: '1.0.0'

info: 
   title: Banking services
   name: banking
   version: 1.0.0
   description: Banking extensions
   contact: 
     name: IBM API Connect
     url: https://apiconnect.ibm.com/
     email: myname@ibm.com

portal-visible: true

properties:
  title: "Branch"
  type: "object"
  properties: 
    Branch type: 
      type: "string"
      enum: 
        - "ATM"
        - "Walk in"
    location: 
      type: "object"
      title: "Location"
      properties: 
        city: 
          type: "string"
          default: "San Francisco"
        state: 
          type: "string"
          default: "CA"
        citystate: 
          type: "string"
          description: "This is generated automatically from the previous two fields"
          template: "{{city}}, {{state}}"
          watch: 
            city: "location.city"
            state: "location.state"
  required:
    - Branch type

Procedure

Edit the API definition YAML file and add the reference. For example:

x-ibm-configuration:
      .
      .
      .
  extensions:
    banking: 1.0.0

In your API definition file, add a property whose name must begin with x- and references the name of the extension you created. Specify the values of the properties that were defined in the OpenAPI extension YAML file.
The following example uses the banking extension:
```
      .
      .
      .
x-banking:
  Branch type: ATM
  location:
    city: San Francisco
    state: CA
    citystate: 'San Francisco, CA'
  
```