Adding an OpenAPI (Swagger 2.0) extension to an API definition (API Manager UI)

When you configure a REST or SOAP API definition, you can extend the OpenAPI (Swagger 2.0) specification by adding either a JSON or YAML extension schema depending on the version of IBM® API Connect you are using. You can also replace an extension with an updated version.

{
  "extension": "1.0.0",
  "info": {
    "title": "Banking services",
    "name": "banking",
    "version": "1.0.1",
    "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"]
  }
}

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

1. To import an extension into a Catalog, complete the following steps:
   1. If you have not previously pinned the UI navigation pane then click the Navigate to icon .
      The API Manager UI navigation pane opens. To pin the UI navigation pane, click the Pin menu icon .
   2. On the Dashboard of the API Manager UI, select the Catalog that you want to work with.
   3. Click Settings and select the Extensions tab.
   4. Import the schema definition file:
      1. Click the Import icon . The Add Extension Schema window opens.
      2. Enter a Title, Name, and Version for the extension.
      3. Select the JSON file that contains the schema definition for the extension, then click Add Extension. The new extension is added to the list of extensions.
   5. Import the schema definition file:
      1. Click the Import icon . The Import Extension window opens.
      2. Select the YAML file that contains the schema definition for the extension, then click Import. The new extension is added to the list of extensions. The displayed title and version properties are derived from the corresponding property settings in the YAML file. If you import two or more extensions with the same name property in the YAML file but different version properties, they are grouped together in the list. You cannot import two extensions with the same name and version.
   6. Optional: To have instances of the extension sent to the Developer Portal, expand the extension and move the Visible in Developer Portal slider to the On position.
      Set this option if you want the extension to be available for use by application developers rather than being metadata for internal use only.
   7. Optional: To have instances of the extension sent to the Developer Portal, include the portal-visible: true setting in your YAML file; see the previous example.
   8. Click Save.
2. To add an extension to an API, complete the following steps:
   1. If you have not previously pinned the UI navigation pane then click the Navigate to icon .
   2. Click Drafts in the UI navigation pane, and then click APIs.
   3. Click the API that you want to work with.
      The API details page opens.
   4. Navigate to the Extensions section, and click the Add Extension icon .
      The Add Extension window opens.
   5. Select the extension that you want to add, then click Done.
      You can enter a search string to locate the required extension.
   6. To set a value for any of the properties that are defined in the schema, specify the value in the appropriate field. Any validation criteria that are defined in the schema are applied to the value that you specify. The following screen capture shows the property setting pane for the previous bank branch example:
      

      
   7. To replace an extension with a new version, add an extension that has the same value for the name property as an extension that has already been added, but a different value for the version property. The Change Version of Extension window opens; click OK to replace the existing version with the new version, or Cancel to retain the existing version. For example, for the bank branch extension described earlier, the Branch type property might have an additional type added to the enumeration list.