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 extra 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 that is 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.