Model Introduction

The Model is used to describe the request or response data of one API in the JSON format. The API Gateway may use the Model to generate the parameter description document of API, and fill in the example request body in the online debugging. The open API in the API market may also generate related parameter descriptions by the Model.

Model Description Syntax

The API Gateway uses the expansion syntax based on JSON to define the Model. The syntax is simpler and more intuitive than JSON Schema, and makes the defined configuration more convenient under the condition of satisfying the description abilities required by the most scenarios.

The following is a common JSON object:

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

The JSON object itself is a valid Model, and also the simplest Model definition mode. We can directly take the object as the Model definition.

It is equivalent to the following Model definition:

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

In case of no additional statement, each field appearing in the JSON object is required by default. The field value of the JSON object may be used as an example value in the generated document, and also used for automatic parsing of field types. The types currently supported include: string, int, long, float, double, enum, ref(reference), array.

We add comments based on the JSON syntax, namely, we describe the specific definition of a field by a double slash followed by the definition contents.

The comment syntax supports the common text and JSON Schema like syntax. The comments to the common text are mainly used for literal description, and can be used for the document description of fields. But the comments don't affect the nature of fields. The JSON Schema syntax is used to define fields in more details, and the supported attributes include $ref, property, required, description, enum.

The following is an example of a more complex model definition:

{ 
    "Name": "John", // the common text syntax may be used to add literal description here. 
    "age": 22, //{"required": false, "description":" the JSON Schema like syntax is used to define fields, and it is set as optional"}. 
    "gender": "male", //{"enum": ["male", "female"], "description": "enumeration of type field definition"} 
    "address": {}, //{"$ref": "model:GWMD-xk298mJueDs", "description": "external Model reference of field definition"} 
    "height": 180.5F,//automatically parsed to the float type. 
    "weight": 65.8 // automatically parsed to the double type. 
} 

Its own internal Model is also referenced in the Model definition.

{ 
    "homeAddress": { 
        "city": "Beijing", 
        "street": "Chang'an Street" 
    }, //{"property": "AddressModel", "description": " the property attribute is used to define the internal model"}. 
    "officeAddress": {} //{"$ref": "AddressModel", "description": " the internal model defined above is referenced. 
} 

Create Model

Create Simple Model

1.Log in to official website, and click "Management Console" in the upper right corner to quickly enter the console interface.

2.Select "Product Service > API Gateway" to enter the "Grouping Management" page.

3.Click "Group Name" to enter the "Group Details" page.

4.Click "Model Management" in the side bar.

5.Click "New Model" button, and the dialog box of "Add Model" pops up.

6.Input the Model name, definition and description, and click "Confirm" to create Model.

Create Model with Reference

In some scenarios, multiple defined Models include the same structure. These common structures can be separately defined as one Model, and then referenced in other Model. This can reduce the definition redundancy and reduce the maintenance cost.

When the Model is used, its referenced Model will be replaced into the specific field. The gateway allows model to reference Model in multiple levels, namely, ModelA references ModelB, while ModelB may reference ModelC. We should note that no circular reference appears in the Model definition.

The process of creating a Model with reference is basically the same as that of creating a simple Model, and only the Model definitions are slightly different.

We use the following syntax to reference a Model:

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

We use a pair of empty curly braces to replace the field value referenced by the Model to be inserted, and use the JSON form to indicate the resource identification of Model to be referenced in the comment part. The resource identification may be obtained in the Model list or the detailed information.

The Model resource belongs to the group level, and the gateway only allows the reference other defined Models under the same group.

Because of relative flexibility of Model reference, the gateway doesn't verify the correctness of the reference in the Model creation or edition except the specific scenario of using the Model.

Therefore, we should ensure the reference is available when using the reference to define one Model.

View Model

1.Select "Product Service > API Gateway" to enter the "Grouping Management" page.

2.Click "Group Name" to enter the "Group Details" page.

3.Click "Model Management" in the side bar to view the Model list under the current group.

4.Click "Model Name" to view the details of Model.

Modify Model

1.Select "Product Service > API Gateway" to enter the "Grouping Management" page.

2.Click "Group Name" to enter the "Group Details" page.

3.Click "Model Management" in the side bar to view the Model list under the current group.

4.Click the "Edit" button of the corresponding Model in the list to enter the dialog box of "Edit Model".

5.The edition of a dialog box is similar to creation of a dialog box. Click "Confirm" after edition to update the Model.

Delete Model

Note: The gateway doesn't verify the reference relationship in the Model operation process. Please ensure the Model to be deleted is not referenced by other Models in the same group to avoid parsing problems.

1.Select "Product Service > API Gateway" to enter the "Grouping Management" page.

2.Click "Group Name" to enter the "Group Details" page.

3.Click "Model Management" in the side bar to view the Model list under the current group.

4.Click the "Delete" button of the corresponding Model in the list.

5.Click "Conformation" button in the pop-up dialog box to delete the Model.