文档首页/应用与数据集成平台 ROMA Connect/用户指南/服务集成APIC使用指导/管理APIC开放的API/附录：API的Swagger扩展定义
更新时间：2025-12-29 GMT+08:00
查看PDF
分享

附录：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"
          retryCount: "3"
          timeout: 30000
表7 参数说明

参数

是否必选

类型

说明

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

作用域：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所绑定的集成应用名称。

13 x-apigateway-plugins

含义：API网关定义的API插件服务。

作用域：Operation Object

示例：

paths:
  '/path':
    get:
      x-apigateway-plugins: ['Plugin_mock']
表21 参数说明

参数

是否必选

类型

说明

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

参数

是否必选

类型

说明

x-apigateway-is-send-fg-body-base64

否

boolean

是否对与FunctionGraph交互场景的请求体进行Base64编码。

  • true：编码
  • false：不编码

相关文档