Creating a Product definition file

You define a Product by creating a Product definition file.

About this task

You can create a Product definition file in either of the following ways:
  • Create the file in an editor of your choice.
  • Create a Product definition file by using the apic create:product command and then modify it. You can base your Product definition file on the default Product template or on your own custom template.
This topic describes the syntax that is needed for both options and also the structure needed when the file is created in the editor. For details on what you can include in the product definition file, see Product definition schema.
You can create a Product in the CLI by running apic create:product and supplying additional arguments on the command line. For example, you can enter the following text in a single command: 
apic create:product --name product_name --title product_title --filename product_file_name.yaml
--apis "filename_of_api1.yaml filename_of_api2.yaml"
where:
  • product_name is the name for your new Product.
  • product_title is the title of your new Product.
  • product_file_name.yaml is the name of the yaml file that is created for your new Product.
  • filename_of_api1.yaml is the file name of one of the APIs that is used within the new Product.
  • filename_of_api2.yaml is the file name of one of the APIs that is used within the new Product.
Another option is to create a Product interactively in the command line by running apic create:product and following the prompts.
You can see further details and available options for the apic create:product command by entering the command: 
apic create:product --help
You can also create a Product from a custom Handlebars template by using the following command:
apic create:product --template template_filename --title product_title
where template_filename is the name of the Handlebars template to use, and product_title is the title of your Product. A Product template file must have a .hbs file name extension. You can create a template from scratch, or start with the example (default) Product template provided in API and Product definition template examples.

A Product definition file contains the following sections:

  • The specification version
  • An information section
  • A visibility section
  • An APIs section
  • A Plans section

In this topic, YAML is used, but the instructions can be adapted to use JSON. Both .yaml and .yml file extensions are supported, but the use of the .yaml file extension is recommended by yaml.org.

Note: All keys and enumeration values that are specified in this topic are case-sensitive.

Procedure

Structure your Product definition file by completing the following steps:

  1. Set the specification version by adding the following line to the beginning of the file: product: 1.0.0.
    This line specifies the template version, and is always product: 1.0.0.
    Note: The specification version is distinct from your Product version. The specification version refers to this YAML file, while the Product version is by your discretion.
  2. Include an information section with details about the Product, as described in Completing the information section of your Product description.
  3. Include a visibility section that specifies who can view and subscribe to the Product, as described in Specifying the visibility of your Product.
  4. Include an APIs section that references the APIs to be included in the Product, as described in Referencing the APIs for your Product.
  5. Include a Plans section that described the Plans you want include in your Product, as described in Describing Plans in your Product.

Results

You have completed a YAML representation of your Product. A complete example with full indentation can be found in An example YAML representation of a Product.

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.