Creating an OpenAPI definition file

APIs are defined in OpenAPI definition files, in YAML format. You can create a default OpenAPI 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 products:publish command to publish the Product. You can also create a draft API in API Manager by using the apic draft-apis:create command.

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

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

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

apic create:api --help

IBM provides an extension to the OpenAPI specification; this extension is described in IBM extensions to the OpenAPI specification.

Note: Products that contain an API with a Swagger property using regex that include lookahead assertions, such as "(?" cannot be validated or published. An error message is returned. For example:

Product has not been published!
The multipart 'openapi' field contains an OpenAPI definition with validation errors.
    definitions.properties.pattern Does not match format 'regex' (context: (root).definitions.properties.pattern, line: 0, col: 0)
400

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: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.

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

You can create multilingual API and Product documentation by using an x-ibm-languages extension directly in the OpenAPI definition. For more information, see Using x-ibm-languages to create multilingual API and Product documentation.