Creating a Product definition file
You define a Product by creating a Product definition file.
About this task
- Create the file in an editor of your choice.
- Create a Product definition file by using the
apic create:productcommand and then modify it. You can base your Product definition file on the default Product template or on your own custom template.
apic create:productand 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"
- 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.
apic create:productand following the prompts.
apic create:productcommand by entering the command:
apic create:product --help
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.
apic create:product --template template_filename --title product_title
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.
Structure your Product definition file by completing the following steps:
Set the specification version by adding the following line to the beginning of the file:
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.
- Include an information section with details about the Product, as described in Completing the information section of your Product description.
- Include a visibility section that specifies who can view and subscribe to the Product, as described in Specifying the visibility of your Product.
- Include an APIs section that references the APIs to be included in the Product, as described in Referencing the APIs for your Product.
- Include a Plans section that described the Plans you want include in your Product, as described in Describing Plans in your Product.
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.