更新时间:2022-02-21 GMT+08:00

附录:API的Swagger扩展定义

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

1:x-apigateway-auth-type

含义:基于Swagger的apiKey认证格式,定义ROMA Connect支持的特有认证方式。

作用域Security Scheme Object

示例

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"
表1 参数说明

参数

是否必选

类型

说明

type

String

认证类型,仅支持“apiKey”。

name

String

用于认证的参数名称。

  • x-apigateway-auth-type取值为“AppSigv1”时,name填写为Authorization。
  • x-apigateway-auth-type取值为“IAM”或者“IAM_NONE”时,name填写为unused。

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'
表2 参数说明

参数

是否必选

类型

说明

x-apigateway-request-type

String

API类型,支持“public”和“private”。

  • public:公开类型API,可以上架云市场。
  • private:私有类型API,不会被上架云市场。

3:x-apigateway-match-mode

含义:ROMA Connect定义的API请求路径的匹配模式,支持NORMAL和SWA。

作用域Operation Object

示例

paths:
  '/path':
    get:
      x-apigateway-match-mode: 'SWA'
表3 参数说明

参数

是否必选

类型

说明

x-apigateway-match-mode

String

API请求路径的匹配模式,支持“SWA”和“NORMAL”。

  • SWA:前缀匹配,例如API的请求路径为“/test/AA”,使用前缀匹配时,通过/test/AA/BB和/test/AA/CC都可以访问API,但是通过/test/AACC无法访问。
  • NORMAL:绝对匹配。

4:x-apigateway-cors

含义:ROMA Connect定义的API是否支持跨域访问。

作用域Operation Object

示例

paths:
  '/path':
    get:
      x-apigateway-cors: true
表4 参数说明

参数

是否必选

类型

说明

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"
表5 参数说明

参数

是否必选

类型

说明

type

String

后端服务类型,支持“HTTP”、“HTTP-VPC”和“MOCK”。

parameters

x-apigateway-backend.parameters

后端参数定义。

httpEndpoints

x-apigateway-backend.httpEndpoints

HTTP类型后端服务定义。

httpVpcEndpoints

x-apigateway-backend.httpVpcEndpoints

HTTP-VPC类型后端服务定义。

functionEndpoints

x-apigateway-backend.functionEndpoints

FUNCTION类型后端服务定义。

mockEndpoints

x-apigateway-backend.mockEndpoints

MOCK类型后端服务定义。

6.1:x-apigateway-backend.parameters

含义:ROMA Connect定义的API后端参数定义。

作用域x-apigateway-backend

示例

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"
表6 参数说明

参数

是否必选

类型

说明

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类型后端服务定义。

作用域x-apigateway-backend

示例

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"
          timeout: 30000
表7 参数说明

参数

是否必选

类型

说明

address

Array

后端服务地址,格式为:{域名或IP}:{PORT}。

scheme

String

后端请求协议,支持“http”和“https”。

method

String

后端请求方法,支持“GET”、“POST”、“PUT”、“DELETE”、“HEAD”、“OPTIONS”、“PATCH”和“ANY”。

path

String

后端请求路径,支持路径变量。

timeout

Number

后端请求超时时间,单位毫秒,缺省值为5000,取值范围为1-60000。

6.3:x-apigateway-backend.httpVpcEndpoints

含义:ROMA Connect定义的HTTP VPC类型后端服务定义。

作用域x-apigateway-backend

示例

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
表8 参数说明

参数

是否必选

类型

说明

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类型后端服务定义。

作用域x-apigateway-backend

示例

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
表9 参数说明

参数

是否必选

类型

说明

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类型后端服务定义。

作用域x-apigateway-backend

示例

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"
表10 参数说明

参数

是否必选

类型

说明

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"
表11 参数说明

参数

是否必选

类型

说明

type

String

后端服务类型,支持“HTTP”、“HTTP-VPC”和“MOCK”。

name

String

后端策略名称。

parameters

x-apigateway-backend.parameters

后端参数定义。

httpEndpoints

x-apigateway-backend.httpEndpoints

HTTP类型服务定义。

httpVpcEndpoints

x-apigateway-backend.httpVpcEndpoints

HTTP-VPC类型服务定义。

functionEndpoints

x-apigateway-backend.functionEndpoints

FUNCTION类型服务定义。

mockEndpoints

x-apigateway-backend.mockEndpoints

MOCK类型服务定义。

conditions

x-apigateway-backend-policies.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"
表12 参数说明

参数

是否必选

类型

说明

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'
表13 参数说明

参数

是否必选

类型

说明

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
表14 参数说明

参数

是否必选

类型

说明

customRatelimitName

x-apigateway-ratelimits.policy

自定义流控策略。要使用该策略,需将x-apigateway-ratelimit属性值引用为该策略名称。

9.1:x-apigateway-ratelimits.policy

含义:流控策略定义。

作用域x-apigateway-ratelimits

示例

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
表15 参数说明

参数

是否必选

类型

说明

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

x-apigateway-ratelimits.policy.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
表16 参数说明

参数

是否必选

类型

说明

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'
表17 参数说明

参数

是否必选

类型

说明

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
表18 参数说明

参数

是否必选

类型

说明

customAccessControlName

x-apigateway-access-controls.policy

自定义访问控制策略。要使用该策略,需将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
表19 参数说明

参数

是否必选

类型

说明

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'
表20 参数说明

参数

是否必选

类型

说明

x-apigateway-roma-app

String

API所绑定的集成应用名称。