在 API 定义中引用扩展

在线编辑

要在 API 定义 YAML (或 JSON) 文件中引用 OpenAPI 扩展，请在 x-ibm-configuration下添加 extensions 密钥。

准备工作

通过导入其定义文件，将 OpenAPI 扩展添加到API将要发布的任何目录中；有关详细信息，请参阅 《使用 OpenAPI 扩展 》。 如果目标目录不包含 OpenAPI 扩展，那么尝试向其发布 API 将失败。

关于本任务

以下示例显示了以 YAML 格式定义银行分行的扩展定义文件：
extension: '1.0.0'

info: 
   title: Banking services
   name: banking
   version: 1.0.0
   description: Banking extensions
   contact: 
     name: IBM API Connect
     url: https://apiconnect.ibm.com/
     email: myname@ibm.com

properties:
  title: "Branch"
  type: "object"
  properties: 
    Branch type: 
      type: "string"
      enum: 
        - "ATM"
        - "Walk in"
    location: 
      type: "object"
      title: "Location"
      properties: 
        city: 
          type: "string"
          default: "San Francisco"
        state: 
          type: "string"
          default: "CA"
        citystate: 
          type: "string"
          description: "This is generated automatically from the previous two fields"
          template: "{{city}}, {{state}}"
          watch: 
            city: "location.city"
            state: "location.state"
  required:
    - Branch type

下表提供了有关创建 API 扩展时可用字段的更多信息。

表 1. 字段说明
字段 描述 必需 缺省值 示例
version 扩展程序的版本号
注意： 该字段 version 必须遵循版本编号 version.release.modification 规则。
 是 1.0.0
title 扩展程序名称
注意： 和 nametitle 字段必须保持简短，以便能在 API 管理器用户界面中显示。
 是 银行服务
name 扩展名的简称
注意： 该字段 name 必须为单词，且仅可包含字母、数字、连字符和下划线。
 是 银行业
description 扩展程序简介 False 银行服务扩展
termsofservice 该扩展程序的服务条款 False 服务条款
license.name 许可证名称 False IBM API Connect
license.URL URL 查看许可证 False https://apiconnect.ibm.com/
contact.name 联系人姓名 False myname@ibm.com
contact.URL URL 联系该组织 False https://www.example.com/support
contact.email 联系该组织的电子邮件地址 False support@example.com
gateways 该扩展程序支持的网关列表
注意： 该字 gateways 段为可选字段，但如果包含该字段，则必须列出该扩展程序可配合使用的网关类型。
 False
  • datapower-api-gateway
  • datapower-gateway
properties 要包含在 OpenAPI 扩展中的自定义属性。 False 该字 properties 段可自定义，以包含任何有效的 OpenAPI 属性。
properties:
  title: "Branch"
  type: "object"
  properties: 
    Branch type: 
      type: "string"
      enum: 
        - "ATM"
        - "Walk in"

过程

要在 API 定义中启用自定义扩展，请完成以下步骤：
  1. 编辑 API 定义 YAML 文件并添加引用。 例如：
    x-ibm-configuration:
      .
      .
      .
  extensions:
    banking: 1.0.0
  2. 在 API 定义文件中，添加其名称必须以 x- 开头的属性，并引用您创建的扩展的名称。 指定 OpenAPI 扩展 YAML 文件中定义的属性值。
    以下示例使用银行扩展：
    
      .
      .
      .
x-banking:
  Branch type: ATM
  location:
    city: San Francisco
    state: CA
    citystate: 'San Francisco, CA'