Model管理

Model简介

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

Model描述语法

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

以下是一个普通JSON对象：

1{
2    "name": "john",
3    "age": 22
4}

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

它等价于下列Model定义：

1{
2    "name": "john", //{"required": true}
3    "age": 22 //{"required": true}
4}

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

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

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

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

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

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

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

创建Model

创建简单 Model

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

3. 点击分组名称，进入“分组详情”页面。

   

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

   

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

   

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

   

创建带引用Model

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

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

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

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

1{
2    "commonModel": {} //{"$ref": "model:GWMD-WcciMdjfz5K"}
3｝

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

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

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

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

查看Model

1. 选择“产品服务>API网关”，进入“分组管理”页面。
2. 点击分组名称，进入“分组详情”页面。

3. 点击侧栏的“Model管理”，查看当前分组下的Model列表。

   

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

   

修改Model

1. 选择“产品服务>API网关”，进入“分组管理”页面。
2. 点击分组名称，进入“分组详情”页面。

3. 点击侧栏的“Model管理”，查看当前分组下的Model列表。

   

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

   

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

   

删除Model

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

1. 选择“产品服务>API网关”，进入“分组管理”页面。
2. 点击分组名称，进入“分组详情”页面。

3. 点击侧栏的“Model管理”，查看当前分组下的Model列表。

   

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

   

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