附录:API的Swagger扩展定义
ROMA Connect在Swagger原有定义的基础上,定义了特有的API定义项,即扩展定义,如认证方式、后端服务定义等。本章节主要介绍API使用的扩展定义。
1:x-apigateway-auth-type
含义:基于Swagger的apiKey认证格式,定义ROMA Connect支持的特有认证方式。
示例:
securityDefinitions: customize-name-iam: type: "apiKey" name: "unused" in: "header" x-apigateway-auth-type: "IAM" customize-name-app: type: "apiKey" name: "Authorization" in: "header" x-apigateway-auth-type: "AppSigv1" customize-name-iam-none: type: "apiKey" name: "unused" in: "header" x-apigateway-auth-type: "IAM_NONE"
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
type |
是 |
String |
认证类型,仅支持“apiKey”。 |
name |
是 |
String |
用于认证的参数名称。
|
in |
是 |
String |
参数所在位置,仅支持“header”。 |
description |
否 |
String |
参数的描述信息。 |
x-apigateway-auth-type |
是 |
String |
认证方式,支持“AppSigv1”、“IAM”和“IAM_NONE”。 |
2:x-apigateway-request-type
含义:ROMA Connect定义的API类型,支持public和private。
作用域:Operation Object
示例:
paths: '/path': get: x-apigateway-request-type: 'public'
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
x-apigateway-request-type |
是 |
String |
API类型,支持“public”和“private”。
|
3:x-apigateway-match-mode
含义:ROMA Connect定义的API请求路径的匹配模式,支持NORMAL和SWA。
作用域:Operation Object
示例:
paths: '/path': get: x-apigateway-match-mode: 'SWA'
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
x-apigateway-match-mode |
是 |
String |
API请求路径的匹配模式,支持“SWA”和“NORMAL”。
|
4:x-apigateway-cors
含义:ROMA Connect定义的API是否支持跨域访问。
作用域:Operation Object
示例:
paths: '/path': get: x-apigateway-cors: true
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
x-apigateway-cors |
否 |
Boolean |
API是否支持跨域访问。 |
开启跨域访问后,API请求的响应会增加如下Header参数:
参数名称 |
参数值 |
说明 |
---|---|---|
Access-Control-Max-Age |
172800 |
预检响应最大缓存时间。 |
Access-Control-Allow-Origin |
* |
允许访问的域,“*”表示允许任何域的请求。 |
Access-Control-Allow-Headers |
X-Sdk-Date,X-Sdk-Nonce,X-Proxy-Signed-Headers,X-Sdk-Content-Sha256,X-Forwarded-For,Authorization,Content-Type,Accept,Accept-Ranges,Cache-Control,Range |
API请求允许使用的头信息字段。 |
Access-Control-Allow-Methods |
GET,POST,PUT,DELETE,HEAD,OPTIONS,PATCH |
API请求允许使用的请求方法。 |
5:x-apigateway-any-method
含义:ROMA Connect定义的API请求方法,用以匹配未指定定义的HTTP方法。
作用域:Path Item Object
示例:
paths: '/path': get: produces: - application/json responses: "200": description: "get response" x-apigateway-any-method: produces: - application/json responses: "200": description: "any response"
6:x-apigateway-backend
含义:ROMA Connect定义的API后端服务定义。
作用域:Operation Object
示例:
paths: '/users/{userId}': get: produces: - "application/json" responses: default: description: "default response" x-apigateway-request-type: "public" x-apigateway-backend: type: "backend endpoint type"
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
type |
是 |
String |
后端服务类型,支持“HTTP”、“HTTP-VPC”和“MOCK”。 |
parameters |
否 |
后端参数定义。 |
|
httpEndpoints |
否 |
HTTP类型后端服务定义。 |
|
httpVpcEndpoints |
否 |
HTTP-VPC类型后端服务定义。 |
|
functionEndpoints |
否 |
FUNCTION类型后端服务定义。 |
|
mockEndpoints |
否 |
MOCK类型后端服务定义。 |
6.1:x-apigateway-backend.parameters
含义:ROMA Connect定义的API后端参数定义。
示例:
paths: '/users/{userId}': get: produces: - "application/json" parameters: - name: "X-Auth-Token" description: "authorization token" type: "string" in: "header" required: true - name: "userId" description: "user name" type: "string" in: "path" required: true responses: default: description: "default response" x-apigateway-request-type: "public" x-apigateway-backend: type: "HTTP" parameters: - name: "userId" value: "userId" in: "query" origin: "REQUEST" description: "user name" - name: "X-Invoke-User" value: "apigateway" in: "header" origin: "CONSTANT" description: "invoke user"
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
name |
是 |
String |
参数名称,由字母、数字、下划线、连线、点组成,以字母开头,最长32字节。 header位置的参数名称不区分大小写。 |
value |
是 |
String |
参数值,当参数映射来源为“REQUEST”时,值为前端请求参数名称。 |
in |
是 |
String |
参数位置,支持“header”、“query”和“path”。 |
origin |
是 |
String |
参数映射来源,支持“REQUEST”和“CONSTANT”。 |
description |
否 |
String |
参数描述信息。 |
6.2:x-apigateway-backend.httpEndpoints
含义:ROMA Connect定义的HTTP类型后端服务定义。
示例:
paths: '/users/{userId}': get: produces: - "application/json" parameters: - name: "X-Auth-Token" description: "authorization token" type: "string" in: "header" required: true responses: default: description: "default response" x-apigateway-request-type: "public" x-apigateway-backend: type: "HTTP" httpEndpoints: address: "www.example.com" scheme: "http" method: "GET" path: "/users" retryCount: "3" timeout: 30000
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
address |
是 |
Array |
后端服务地址,格式为:{域名或IP}:{PORT}。 |
scheme |
是 |
String |
后端请求协议,支持“http”和“https”。 |
method |
是 |
String |
后端请求方法,支持“GET”、“POST”、“PUT”、“DELETE”、“HEAD”、“OPTIONS”、“PATCH”和“ANY”。 |
path |
是 |
String |
后端请求路径,支持路径变量。 |
retryCount |
否 |
String |
后端失败重试次数。 |
timeout |
否 |
Number |
后端请求超时时间,单位毫秒,缺省值为5000,取值范围为1-60000。 |
6.3:x-apigateway-backend.httpVpcEndpoints
含义:ROMA Connect定义的HTTP VPC类型后端服务定义。
示例:
paths: '/users/{userId}': get: produces: - "application/json" parameters: - name: "X-Auth-Token" description: "authorization token" type: "string" in: "header" required: true responses: default: description: "default response" x-apigateway-request-type: "public" x-apigateway-backend: type: "HTTP-VPC" httpVpcEndpoints: name: "vpc-test-1" scheme: "http" method: "GET" path: "/users" timeout: 30000
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
name |
是 |
Array |
VPC通道名称。 |
scheme |
是 |
String |
后端请求协议定义,支持“http”和“https”。 |
method |
是 |
String |
后端请求方法,支持“GET”、“POST”、“PUT”、“DELETE”、“HEAD”、“OPTIONS”、“PATCH”和“ANY”。 |
path |
是 |
String |
后端请求路径,支持路径变量。 |
timeout |
否 |
Number |
后端请求超时时间,单位毫秒,缺省值为5000,取值范围为1-60000。 |
6.4:x-apigateway-backend.functionEndpoints
含义:ROMA Connect定义的FUNCTION类型后端服务定义。
示例:
paths: '/users/{userId}': get: produces: - "application/json" parameters: - name: "X-Auth-Token" description: "authorization token" type: "string" in: "header" required: true responses: default: description: "default response" x-apigateway-request-type: "public" x-apigateway-backend: type: "FUNCTION" functionEndpoints: version: "v1" function-urn: "" invocation-type: "synchronous" timeout: 30000
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
function-urn |
是 |
String |
函数的URN地址。 |
version |
是 |
String |
函数的版本。 |
invocation-type |
是 |
String |
函数的调用类型,支持“async”和“sync”。 |
timeout |
否 |
Number |
函数超时时间,单位毫秒,缺省值为5000,取值范围为1-60000。 |
6.5:x-apigateway-backend.mockEndpoints
含义:ROMA Connect定义的MOCK类型后端服务定义。
示例:
paths: '/users/{userId}': get: produces: - "application/json" parameters: - name: "X-Auth-Token" description: "authorization token" type: "string" in: "header" required: true responses: default: description: "default response" x-apigateway-request-type: "public" x-apigateway-backend: type: "MOCK" mockEndpoints: result-content: "mocked"
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
result-content |
是 |
String |
MOCK返回结果。 |
7:x-apigateway-backend-policies
含义:ROMA Connect定义的API后端策略。
作用域:Operation Object
示例:
paths: '/users/{userId}': get: produces: - "application/json" responses: default: description: "default response" x-apigateway-request-type: "public" x-apigateway-backend: type: "backend endpoint type" x-apigateway-backend-policies: - type: "backend endpoint type" name: "backend policy name" conditions: - type: "equal/enum/pattern", value: "string", origin: "source/request_parameter", parameter_name: "string"
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
type |
是 |
String |
后端服务类型,支持“HTTP”、“HTTP-VPC”和“MOCK”。 |
name |
是 |
String |
后端策略名称。 |
parameters |
否 |
后端参数定义。 |
|
httpEndpoints |
否 |
HTTP类型服务定义。 |
|
httpVpcEndpoints |
否 |
HTTP-VPC类型服务定义。 |
|
functionEndpoints |
否 |
FUNCTION类型服务定义。 |
|
mockEndpoints |
否 |
MOCK类型服务定义。 |
|
conditions |
是 |
后端策略条件。 |
7.1:x-apigateway-backend-policies.conditions
含义:ROMA Connect定义的API后端策略条件。
作用域:x-apigateway-backend-policies
示例:
paths: '/users/{userId}': get: produces: - "application/json" responses: default: description: "default response" x-apigateway-request-type: "public" x-apigateway-backend: type: "backend endpoint type" x-apigateway-backend-policies: - type: "backend endpoint type" name: "backend policy name" conditions: - type: "equal/enum/pattern", value: "string", origin: "source/request_parameter", parameter_name: "string"
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
type |
是 |
String |
策略条件类型,支持“equal”、“enum”和“pattern”。 |
value |
是 |
String |
策略条件值。 |
origin |
是 |
String |
策略条件输入来源,支持“source”和“request”。 |
parameter |
否 |
String |
策略条件输入来源为“request”时,请求入参的名称。 |
8:x-apigateway-ratelimit
含义:ROMA Connect引用的流控策略。
作用域:Operation Object
示例:
paths: '/path': get: x-apigateway-ratelimit: 'customRatelimitName'
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
x-apigateway-ratelimit |
否 |
String |
引用的流控策略名称,设置为“customRatelimitName”。 |
9:x-apigateway-ratelimits
含义:流控策略名称与关联策略映射。
作用域:Swagger Object
示例:
x-apigateway-ratelimits: customRatelimitName: api-limit: 200 app-limit: 200 user-limit: 200 ip-limit: 200 interval: 1 unit: second/minute/hour shared: true special: - type: APP limit: 100 instance: xxxxxxxxx
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
customRatelimitName |
否 |
自定义流控策略。要使用该策略,需将x-apigateway-ratelimit属性值引用为该策略名称。 |
9.1:x-apigateway-ratelimits.policy
含义:流控策略定义。
示例:
x-apigateway-ratelimits: customRatelimitName: api-limit: 200 app-limit: 200 user-limit: 200 ip-limit: 200 interval: 1 unit: MINUTE shared: false special: - type: USER limit: 100 instance: xxxxxxx
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
api-limit |
是 |
Number |
API访问次数限制。 |
user-limit |
否 |
Number |
用户访问次数限制。 |
app-limit |
否 |
Number |
应用访问次数限制。 |
ip-limit |
否 |
Number |
源IP访问次数限制。 |
interval |
是 |
Number |
流控策略时间周期。 |
unit |
是 |
String |
流控策略时间周期单位,支持“SECOND”、“MINUTE”、“HOUR”和“DAY”。 |
shared |
否 |
Boolean |
是否共享流控策略。 |
special |
否 |
特殊流控策略。 |
9.2:x-apigateway-ratelimits.policy.special
含义:特殊流控策略定义。
作用域:x-apigateway-ratelimits.policy
示例:
x-apigateway-ratelimits: customRatelimitName: api-limit: 200 app-limit: 200 user-limit: 200 ip-limit: 200 interval: 1 unit: MINUTE shared: false special: - type: USER limit: 100 instance: xxxxxxxx
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
type |
是 |
String |
特殊流控策略类型,支持“APP”和“USER”。 |
limit |
是 |
Number |
访问次数限制。 |
instance |
是 |
String |
特殊APP或USER的对象标识。 |
10:x-apigateway-access-control
含义:ROMA Connect引用的访问控制策略。
作用域:Operation Object
示例:
paths: '/path': get: x-apigateway-access-control: 'customAccessControlName'
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
x-apigateway-access-control |
否 |
String |
引用的访问控制策略名称,设置为“customAccessControlName”。 |
11:x-apigateway-access-controls
含义:访问控制策略名称与关联策略映射。
作用域:Swagger Object
示例:
x-apigateway-access-controls: customAccessControlName: acl-type: "DENY" entity-type: "IP" value: 127.0.0.1,192.168.0.1/16
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
customAccessControlName |
否 |
自定义访问控制策略。要使用该策略,需将x-apigateway-access-control属性值引用为该策略名称。 |
11.1:x-apigateway-access-controls.policy
含义:访问控制策略定义。
作用域:x-apigateway-access-controls
示例:
x-apigateway-access-controls: customAccessControlName: acl-type: "DENY" entity-type: "IP" value: 127.0.0.1,192.168.0.1/16
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
acl-type |
是 |
String |
访问控制行为,支持“PERMIT”和“DENY”。 |
entity-type |
是 |
String |
访问控制对象,仅支持“IP”。 |
value |
是 |
String |
访问控制策略值,多个值之间以英文逗号(,)隔开。 |
12:x-apigateway-roma-app
含义:API绑定的集成应用。
作用域:Operation Object
示例:
paths: '/path': get: x-apigateway-roma-app: 'romaAppName'
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
x-apigateway-roma-app |
是 |
String |
API所绑定的集成应用名称。 |
13 x-apigateway-plugins
含义:API网关定义的API插件服务。
作用域:Operation Object
示例:
paths: '/path': get: x-apigateway-plugins: ['Plugin_mock']
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
x-apigateway-plugins |
否 |
Array |
API所绑定的插件名列表。 |
14 x-apigateway-is-send-fg-body-base64
含义:是否对与FunctionGraph交互场景的请求体进行Base64编码,boolean类型。
作用域:Operation Object
示例:
paths: '/path': get: "x-apigateway-is-send-fg-body-base64": true
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
x-apigateway-is-send-fg-body-base64 |
否 |
boolean |
是否对与FunctionGraph交互场景的请求体进行Base64编码。
|