文档首页> 应用与数据集成平台 ROMA Connect> 用户指南> 服务集成指导> API管理> 附录：API的Swagger扩展定义

更新时间：2023-03-01 GMT+08:00

附录：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"

表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所绑定的插件名列表。

父主题： API管理

上一篇：添加简易认证凭据

下一篇：自定义后端管理

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消