IBM extensions to the OpenAPI (Swagger 2.0) specification
You use the x-ibm-configuration
object in your OpenAPI (Swagger 2.0) definition file to add extensions
that are specific to IBM® API
Connect.
The x-ibm-configuration extension has the following structure:
x-ibm-configuration:
enforced: enforced_boolean
phase: Phase
testable: test_boolean
cors:
enabled: cors_boolean
assembly:
execute:
- assembly_component
properties:
properties_extension
catalogs:
catalogs_extension
The following table lists the various extensions used by API Connect, whether they are required, a description of their use and behavior, and their type.
Extension | Required | Description | Type |
---|---|---|---|
phase | Yes | Use the phase extension to describe the maturity of the API. It can take the
following values:
|
String |
testable | Yes | Use the testable extension to specify whether the API can be
tested using the test tool in the Developer Portal. |
Boolean |
enforced | Yes | Use the enforced extension to specify if the API Connect gateway is
used to enforce the API.
|
Boolean |
cors | Yes | Use the cors extension to specify whether CORS access control
is used for the API. The extension has an enabled field which is a
Boolean. |
Object (with a single Boolean field) |
assembly | No | Use the assembly extension to describe the application of
policies and logic to an API. It contains an execute field that
contains an array of policies that are applied in order. It can contain a
catch field that contains an array of error cases to be
caught.For information about use of the For information about use of the
|
Object |
gateway | No | Use the gateway extension to specify which type of gateway you
want to use. If you are using a DataPower® Gateway or Micro Gateway, it must be
included and take one of the following values:
|
String |
properties | No | Use the properties extension to define properties for use in
an API. |
Object (properties) |
catalogs | No | Use the catalogs extension to define Catalog-specific values
for properties defined in the properties extension. |
Object (catalogs) |
The following example shows the x-ibm-extension
section of an API that is
enforced by API Connect, is in the
realized state, is testable through the test tool in the Developer Portal, has CORS access
control enabled, and has a simple assembly that invokes a URL and then redacts a field from the
request or response.
x-ibm-configuration:
enforced: true
phase: realized
testable: true
cors:
enabled: true
assembly:
execute:
- invoke:
title: Example Invoke
target-url: 'https://example.com/api'
description: Example description
- redact:
actions:
- action: redact
from:
- request
- response
path: //*[@name='secondaryAddress']/*[@name='streetAddress']
properties:
ID:
value: 1234
description: An ID to be used for validating.
encoded: false
catalogs:
Sandbox:
properties:
ID: 5678