附录：自定义后端的Swagger扩展定义

概述

ROMA Connect在Swagger原有定义的基础上，定义了特有的API定义项，即扩展定义，如认证方式、函数脚本定义等。本章节主要介绍自定义后端使用的扩展定义。

1：x-livedata-auth-type

含义：基于Swagger的apiKey认证格式，定义自定义后端支持的特有认证方式。

示例：

securityDefinitions:
  customize-name-signature:
    type: "apiKey"
    name: "Authorization"
    in: "header"
    x-livedata-auth-type: "SIGNATURE"
    x-livedata-signature:
      key: "signatureKey"
      secret: "signatureSecret"

表1 参数说明
参数	是否必选	类型	说明
type	是	String	认证类型，仅支持“apiKey”。
name	是	String	用于认证的参数名称，填写为Authorization。
in	是	String	参数所在位置，仅支持“header”。
description	否	String	参数的描述信息。
x-livedata-auth-type	是	String	自定义后端的认证方式，仅支持“SIGNATURE”。
x-livedata-signature.key	否	String	签名所需的key。
x-livedata-signature.secret	否	String	签名所需的secret。

2：x-livedata-version

含义：自定义后端定义的版本号。

作用域：Operation Object

示例：

paths:
  '/path':
    get:
      x-livedata-version: '1.0.1'

表2 参数说明
参数	是否必选	类型	说明
x-livedata-version	是	String	API版本号。

3：x-livedata-status

含义：自定义后端的状态。

作用域：Operation Object

示例：

paths:
  '/path':
    get:
      x-livedata-status: 'DESIGNED'

表3 参数说明
参数	是否必选	类型	说明
x-livedata-status	是	String	自定义后端的状态，支持“DESIGNED”、“DEVELOPED”、“TESTED”和“DEPLOYED”。 DESIGNED：自定义后端处于已设计、待开发状态。 DEVELOPED：自定义后端处于已开发、待测试状态。 TESTED：自定义后端处于已测试、待部署状态。 DEPLOYED：自定义后端处于已部署状态。

4：x-livedata-roma-app

含义：自定义后端绑定的集成应用。

作用域：Operation Object

示例：

paths:
  '/path':
    get:
      x-livedata-roma-app: 'romaAppName'

表4 参数说明
参数	是否必选	类型	说明
x-livedata-roma-app	是	String	自定义后端绑定的集成应用。

5：x-livedata-scripts

含义：自定义后端定义的脚本。

作用域：Operation Object

示例：

paths:
  '/path':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-livedata-scripts:
        - type: "function"
          content: "custom-script-content"
          result: "func"

表5 参数说明
参数	是否必选	类型	说明
content	是	String	脚本语句，格式为经base64编码的字符串，实际脚本需经过base64解码后获取。
result	是	String	返回对象，执行语句的执行结果将封装在该对象中返回。该参数仅对数据后端生效，函数后端不使用。
type	是	String	脚本类型，支持“function”、“SQL”和“SP”。
datasources	否	x-livedata-scripts.datasources	数据源定义。

5.1 x-livedata-scripts.datasources

含义：自定义后端的数据源定义。

作用域：x-livedata-scripts

示例：

paths:
  '/users':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-livedata-scripts:
        - type: "function"
          content: "custom-script-content"
          result: "custom-script-result"
          datasource:
            name: "custom-datasource-name"