Preparing and Adding Swagger API Data Sources¶

EnOS Digital Twins Visualization can connect to external data sources data via the Swagger API.

Preparing Swagger doc¶

This article describes how to use the Swagger API specification to interface data to DTV. The swagger doc provided by the service used by the user needs to follow the Official Swagger Specification

Interface¶

To get the data and use it for Digital Twin visualization, you need to use the following interface in the Swagger doc to get the data.

Get Entity¶

Please define the fields in the interface according to the following example.

Use key: {path} to define the interface path as the unique key. Use name: paths.{path}.get.summary to define the summary field as the page display name. Add in: "query" to paths.{path}.get.parameters to pass parameters[index].name as param key to the interface. Use parameters[index].type == "content" to define the data as content. Use parameters[index].enum = ["option1", "option2"] to define the data as dropdown options. Use format == "date-time" to define the data as a date.

Get Fields¶

Please define the fields in the interface according to the following example.

To parse the paths.{path}.get.responses[200].schema field, the type must be array. Use paths.{path}.get.responses[200].schema.originalRef to get the structure of the entity. Use the definitions[originalRef].properties structure to define the properties to be returned. Using definitions[originalRef].properties[property].description, define [property] to be the key of the returned data and description to be the name of the returned data (or the same as the key if there is no description).

Swagger doc Sample¶

{
    "swagger": "2.0",
    "info": {
        "description": "API management platform",
        "version": "1.0",
        "title": "API management Restful APIs",
        "termsOfService": "http://localhost:xxxx/",
        "contact": {
            "name": "EnOS Cloud QA team",
            "email": "xxx@envision-xxxx.com"
        }
    },
    "host": "172.16.47.25:xxxx",
    "basePath": "/",
    "tags": [
        {
            "name": "dtv",
            "description": "Api Group Controller"
        }
    ],
    "paths": {
        "/jarvis/group/list": {
            "get": { // Digital Twin Visualization only scans get requests
                "tags": [
                    "dtv", // For data interfaces that need to connect to the Digital Twin visualization via the Swagger API, you need to tag them with dtv
                ],
                "summary": "Summary:Digital Twin Visual Interface: Project List Presentation",
                "description": "DTV Interface Comments",
                "operationId": "listUsingGET",
                "produces": [
                    "*/*"
                ],
                "parameters": [
                    {
                        "name": "projectId",
                        "in": "query", // Add `in: "query"` to pass parameters[index].name as param key to the interface
                        "description": "projectId",
                        "required": true,
                        "type": "string" // To display as a drop-down option, provide the enum field; for a date, set the format to `date-time` or `date`.
                    }
                ],
                "responses": { //The data interface returns data of type JSON array in the following format. originalRef of items refers to the item entity definition.
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "originalRef": "MjolnirApiGroup",
                                "$ref": "#/definitions/MjolnirApiGroup"
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Not Found"
                    }
                },
                "deprecated": false
            }
        }
    },
    "definitions": {
        "MjolnirApiGroup": {
            "type": "object",
            "properties": {
                "createdTime": {
                    "type": "string",
                    "format": "date"
                },
                "dateStringContent": {
                    "type": "string",
                    "format": "date"
                },
                "id": { // For each prop in properties, you can add a description to define the display column name of the data item; you can add a type to define the data type. The format is as follows.
                    "type": "string",
                    "description": "Project ID"
                },
                "javaUtilDate": {
                    "type": "string",
                    "format": "date"
                },
                "javaUtilDateTime": {
                    "type": "string",
                    "format": "date-time"
                },
                "name": { // is the key of the returned data
                    "type": "string",
                    "description": "Project Name" // is the name of the returned data, or the same as the key if there is no description.
                },
                "projectId": {
                    "type": "string"
                },
                "status": {
                    "type": "integer",
                    "format": "int32"
                },
                "updatedTime": {
                    "originalRef": "Timestamp",
                    "$ref": "#/definitions/Timestamp"
                }
            },
            "title": "MjolnirApiGroup"
        }
    }
}

Verify Swagger doc¶

You can use Swagger’s Get Data interface to verify that the Swagger doc configuration is valid: the request is made with the host + swaggerPath + query parameter + fields, as shown in the example below.

http://jarvis.apaas-cn2.eniot.io//jarvis/group/list?fields=dateStringContent,id&projectId=aaa

Connecting to the Digital Twin Visualization¶

Add this type of external data source by following the steps

Select Dashboards > Data Sources from the left navigation pane.
Select the External Data Sources tab.
Select New Data Source and provide the required information.
- Type: Select Swagger API
- Name: Specify the name of the data source
- Visibility: Specify the scope of the data source
  - Internal: For this OU only
  - Public: Available for other OUs
- Host: Enter the database host address
- Doc Path: Enter the document path.
- In the Metadata Cache input box, you can specify when the DTV will clear the metadata cache.
- In the Data Cache input box, you can specify the time when the DTV will clear the data cache.
Select OK.

The configured Swagger API external data source can now be selected in the Chart Editor.

Return Code¶

After selecting the Swagger API data source in the widget, you need to check the return code to confirm whether the request is successful. If the return code is 0, then the data connection is successful; if other codes are returned, then the data connection fails.

Success Sample¶

{
"code": 0,
"message": "Success",
"data": exampledata
}

Failure Sample¶

{
"code": 500,
"message": "Error message"
}