创建产品定义文件

通过创建产品定义文件来定义产品。

关于此任务

可通过以下任一方式来创建产品定义文件:
  • 在您选择的编辑器中创建该文件。
  • 使用 apic create:product 命令创建产品定义文件,然后对其进行修改。 您可以将产品定义文件建立在缺省产品模板或您自己的定制模板的基础上。
本主题描述了这两个选项所需的语法以及在编辑器中创建该文件时所需的结构。 有关产品定义文件可包含的内容,请参阅产品定义模式
可通过运行 apic create:product 并在命令行上提供其他自变量以在 CLI 中创建产品。 例如,可在一条命令中输入以下文本:
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 为新产品的名称。
  • product_title 为新产品的标题。
  • product_file_name.yaml 为针对新产品创建的 yaml 文件的名称。
  • filename_of_api1.yaml 为新产品中使用的某一 API 的文件名。
  • filename_of_api2.yaml 为新产品中使用的某一 API 的文件名。
另一个选项是在命令行中通过运行 apic create:product,然后按照提示操作,以交互方式创建产品。
您可以输入以下命令来查看 apic create:product 命令的进一步详细信息和可用选项:
apic create:product --help
您还可以使用以下命令,从定制 Handlebars 模板创建产品:
apic create:product --template template_filename --title product_title
其中 template_filename 是要使用的 Handlebars 模板的名称,product_title 是产品的标题。 产品模板文件必须具有 .hbs 文件扩展名。 您可以从头开始创建模板,也可以从 API 和产品定义模板示例中提供的示例(默认)产品模板开始。

产品定义文件包含以下节:

  • 规范版本
  • “信息”节
  • “可视性”节
  • API 节
  • “计划”节

在此主题中,将使用 YAML,但可以调整指示信息来使用 JSON。 .yaml.yml 文件扩展名都支持,但建议使用.yaml 文件扩展名。 yaml.org.

注: 本主题中指定的所有键和枚举值都区分大小写。

过程

完成以下步骤来组织产品定义文件:

  1. 通过将以下行添加到文件开头来设置规范版本: product: 1.0.0
    此行用于指定模板版本,并且始终为 product: 1.0.0
    注: 规范版本与产品版本不同。 规范版本是指此 YAML 文件,而产品版本由您自行决定。
  2. 包含有关产品详细信息的信息部分,如完成产品描述的信息部分中所述。
  3. 如 " 指定产品的可见性 "中所述,包含一个可见性部分,指定谁可以查看和订阅产品。
  4. 包含一个 API 部分,其中引用了产品中要包含的 API,如引用产品的 API 中所述。
  5. 包括一个计划部分,描述您想要包含在产品中的计划,如描述产品中的计划中所述。

结果

您已完成了产品的 YAML 表示。 带完整缩进的完整示例可在《 产品的 YAML 表示示例 》中找到。

您可以直接在 OpenAPI 定义中使用 x-ibm-languages 扩展来创建多语言 API 和产品文档。 有关详细信息,请参阅使用 x-ibm-languages 创建多语言 API 和产品文档