Model管理
所有文档

          API网关

          Model管理

          Model简介

          Model用于描述一个API的JSON格式请求或响应数据,API网关可以使用该Model来生成API的参数说明文档、在线调试时填充示例请求体,对于在API市场开放的API,也可通过该Model生成相关参数说明。

          Model描述语法

          API网关使用基于JSON的扩充语法来定义Model,该语法比JSON Schema更加简单、直观,在满足大部分场景所需描述能力的情况下,让定义的配置更便捷。

          以下是一个普通JSON对象:

          {
              "name": "john",
              "age": 22
          }

          JSON对象本身就是合法的Model,也是最简单的Model定义方式,我们可以直接将该对象作为Model定义。

          它等价于下列Model定义:

          {
              "name": "john", //{"required": true}
              "age": 22 //{"required": true}
          }

          若没有额外声明,默认情况下JSON对象中出现的每个字段都是必须的。JSON对象的字段值会在生成的文档中作为示例值,同时也用于字段类型的自动解析。目前支持的类型有以下几种:string、int、long、float、double、enum、ref(引用)、array。

          我们在JSON的语法基础上增加了注释,即用双斜杠跟上定义内容来描述字段的具体定义。

          注释语法支持普通文本和类JSON Schema语法。普通文本的注释主要用于文字性描述,可被用于字段的文档说明,但不会对字段的性质产生影响。JSON Schema语法用于更加详细地定义字段,支持的属性有 $ref、property、required、description、enum。

          下面是一个更加复杂的Model定义示例:

          {
              "name": "john", //可使用普通文本语法在此处添加文字性描述
              "age": 22, //{"required": false, "description": "使用类JSON Schema语法定义字段,将其设为可选"}
              "gender": "male", //{"enum": ["male", "female"], "description": "枚举类型字段定义"}
              "address": {}, //{"$ref": "model:GWMD-xk298mJueDs", "description": "为字段定义外部Model引用"}
              "height": 180.5F, //自动解析为float类型
              "weight": 65.8 //自动解析为double类型
          }

          Model定义中还可引用自身的内部Model:

          {
              "homeAddress": {
                  "city": "Beijing",
                  "street": "Chang'an Street"
              }, //{"property": "AddressModel", "description": "使用property属性定义内部model"}
              "officeAddress": {} //{"$ref": "AddressModel", "description": "引用上面定义的内部model"}
          }

          创建Model

          创建简单 Model

          1. 登录百度智能云官网,点击右上角的“管理控制台”,快速进入控制台界面。
          2. 选择“产品服务>API网关”,进入“分组管理”页面。
          3. 点击分组名称,进入“分组详情”页面。

            image.png

          4. 点击侧栏的“Model管理”。

            image.png

          5. 点击“新增Model”按钮,会弹出新增Model的对话框。

            image.png

          6. 输入Model名称、定义及描述,点击“确定”完成Model的创建。

            image.png

          创建带引用Model

          有些场景下,定义的多个Model中都包含了相同结构。这些共同的结构可以被单独定义为一个Model,然后在其它Model中引用,这样就能够减少定义的冗余,降低维护成本。

          当该Model被使用时,其引用的Model会被替换到具体的字段。网关允许Model进行多层的引用,即ModelA引用ModelB,而ModelB可再引用ModelC。需要注意的是,不要在Model定义中出现循环引用的情况。

          创建带引用Model的过程与创建简单Model的过程基本一致,只不过Model定义略有不同。

          我们使用如下语法来引用一个Model:

          {
              "commonModel": {} //{"$ref": "model:GWMD-WcciMdjfz5K"}

          我们将待插入Model引用的字段值,用一对空花括号代替,在注释部分用 JSON 形式注明要引用Model的资源标识,该资源标识可在Model列表或详细信息中获取。

          Model资源属于分组级别,网关只允许引用同分组下定义的其它Model。

          由于Model的引用相对灵活,在创建或编辑Model时,网关不会校验引用的正确性,只有在具体使用该Model的场景下会进行校验。

          因此,当使用引用来定义一个Model时,需要自行确保引用可用。

          查看Model

          1. 选择“产品服务>API网关”,进入“分组管理”页面。
          2. 点击分组名称,进入“分组详情”页面。
          3. 点击侧栏的“Model管理”,查看当前分组下的Model列表。

            model_created.png

          4. 点击Model名称,即可在右侧查看Model的详情信息。

            model_detail.png

          修改Model

          1. 选择“产品服务>API网关”,进入“分组管理”页面。
          2. 点击分组名称,进入“分组详情”页面。
          3. 点击侧栏的“Model管理”,查看当前分组下的Model列表。

            model_created.png

          4. 在列表中点击对应Model的“编辑”按钮,进入编辑Model对话框。

            image.png

          5. 编辑对话框与创建对话框类似,编辑完毕后点击确定,完成Model的更新。

            model_edit_dialog.png

          删除Model

          注意:网关不会在操作Model过程中校验引用关系,请确保要删除的Model未被同分组其它Model引用,避免出现解析问题。

          1. 选择“产品服务>API网关”,进入“分组管理”页面。
          2. 点击分组名称,进入“分组详情”页面。
          3. 点击侧栏的“Model管理”,查看当前分组下的Model列表。

            model_created.png

          4. 在列表中点击对应Model的“删除”按钮。

            image.png

          5. 在弹出的对话框中点击“确认”按钮,删除Model。

            image.png

          上一篇
          流控管理
          下一篇
          跨域资源共享CORS