# 附录：API的Swagger扩展定义
ROMA Connect在Swagger原有定义的基础上，定义了特有的API定义项，即扩展定义，如认证方式、后端服务定义等。本章节主要介绍API使用的扩展定义。
#### 1：x-apigateway-auth-type
**含义**：基于Swagger的apiKey认证格式，定义ROMA Connect支持的特有认证方式。
**作用域** ：[Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object)
**示例**：
```
paths:
  '/path':
    get:
      x-apigateway-ratelimit: 'customRatelimitName'
```
表13参数说明 
| 参数                     | 是否必选 | 类型     | 说明                                  |
|:---|:---|:---|:---|
| x-apigateway-ratelimit | 否    | String | 引用的流控策略名称，设置为"customRatelimitName"。 |
   
 #### 9：x-apigateway-ratelimits
**含义**：流控策略名称与关联策略映射。
**作用域** ：[Swagger Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object)
**示例**：
```
paths:
  '/path':
    get:
      x-apigateway-access-control: 'customAccessControlName'
```
表17参数说明 
| 参数                          | 是否必选 | 类型     | 说明                                        |
|:---|:---|:---|:---|
| x-apigateway-access-control | 否    | String | 引用的访问控制策略名称，设置为"customAccessControlName"。 |
   
 #### 11：x-apigateway-access-controls
**含义**：访问控制策略名称与关联策略映射。
**作用域** ：[Swagger Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#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：不编码   |