Creating an OpenAPI (Swagger 2.0) definition file

APIs are defined in OpenAPI (Swagger 2.0) definition files, in YAML format. You can create a default OpenAPI (Swagger 2.0) definition file by using the create command and then modify it by using an editor of your choice.

You can stage or publish the API directly to a Catalog in API Manager by referencing the API in a Product definition file, and then using the apic publish command to publish the Product. You can also create a draft API in API Manager by using the push command.

You can create an API in the CLI by running apic create --type api, and add additional arguments on the command line.

Another option is to create an API interactively in the command line by running apic create --type api and following the prompts.

You can see further details and available options for the apic create --type api command by running:

apic create --type api --help

IBM® provides an extension to the OpenAPI (Swagger 2.0) specification; this extension is described in IBM extensions to the OpenAPI (Swagger 2.0) specification.

Creating an API definition from a template

You can use a custom Handlebars template to create an API by using the following command:

apic create --type api --template template_filename --title api_title

where template_filename is the name of the Handlebars template to use, and api_title is the title of your API.

Instead of supplying the --template option, you can set the following configuration variables:

template-default-api - specifies the base file name of the .hbs template file.
template-path - specifies the directory containing the template file.

For more information, see Creating and using API and Product definitions templates.

An API template file must have a .hbs filename extension. You can create a template from scratch, or start with the example (default) API template provided in API and Product definition template examples.

From IBM API Connect Version 5.0.7.2, you can create multilingual API and Product documentation by using an x-ibm-languages extension directly in the OpenAPI (Swagger 2.0) definition. For more information, see Using x-ibm-languages to create multilingual API and Product documentation.