Creating an example

You add examples to an API to make the specification of your API clearer.

Before you begin

Launch the example creation window. For details of the areas in your API definition from where you can create an example, see the following topics:

About this task

Note:
  • This task relates to configuring an OpenAPI 3.0 API definition. For details on how to configure an OpenAPI 2.0 API definition, see Editing an OpenAPI 2.0 API definition.
  • OpenAPI 3.0 APIs are supported only with the DataPower® API Gateway, not with the DataPower Gateway (v5 compatible).
  • For details of current OpenAPI 3.0 support limitations, see OpenAPI 3.0 support in IBM® API Connect.

You can complete this task either by using the API Designer UI application, or by using the browser-based API Manager UI.

At any time, you can switch directly to the underlying OpenAPI YAML source by clicking the Source icon OpenAPI Source icon. To return to the design form, click the Form icon Form icon.

Procedure

  1. Create the example; you can either create an example from scratch, or you can reference an example that is defined in an example component.
    • To create the example from scratch, provide the following information on the Definition tab:
      • Example Name: If you are creating an example component, this name defines a key that enables this example to be referenced from elsewhere in the API definition; the reference has the following format:
        #/components/examples/Name
      • Summary: A summary description of the example.
      • Description: A full description of the example. You can use CommonMark syntax for rich text representation.
      • External Value: A URL that points to a literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. This could a PDF, for example.
    • To reference an example that is defined in an example component, provide the following information on the Reference tab:
      • Example Name: If you are creating an example component, this name defines a key that enables this example to be referenced from elsewhere in the API definition; the reference has the following format:
        #/components/examples/Name
      • Reference from: Select a reference to an example component.
  2. Click Create.
    The example details are displayed for further editing; see Editing an example.