文档首页/ API网关 APIG/ API参考（巴黎区域）/ 共享版API/ OpenAPI接口/ 导入API到已有分组

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

导入API到已有分组

功能介绍

导入swagger格式的文件, 在已有分组中创建或更新API。swagger文件支持json以及yaml格式。

URI

HTTP/HTTPS请求方法以及URI如下表所示。

表1
请求方法	URI
PUT	/v1.0/apigw/openapi?group_id={0}&mode={1}

URI中的参数说明如下表所示。

表2 参数说明
参数	是否必选	类型	说明
group_id	是	String	分组 ID
mode	是	String	导入模式，可选merge和override。当API定义冲突时，merge保留原有API，override会覆盖原有API。
extend_mode	否	String	扩展信息导入模式，可选merge和override。当扩展信息定义冲突时，merge保留原有扩展信息，override会覆盖原有扩展信息。

请求消息

表3 参数说明
名称	是否必选	参数类型	说明
swagger	是	String	固定值2.0
info	是	Object	参考表4
paths	是	Object	参考表 paths参数说明
responses	否	Object	公用响应定义，可以被引用在{method}的操作中，参考表9
securityDefinitions	是	Object	定义鉴权方式，参考表13
x-apigateway-access-controls	否	Object	访问控制信息，参考表 x-apigateway-access-controls参数说明
x-apigateway-ratelimits	否	Object	流量空时信息，参考表 x-apigateway-ratelimits参数说明

表4 info参数说明
名称	是否必选	参数类型	说明
title	否	String	API分组名称，导入到已有分组时不生效
version	否	String	版本号，用户输入自定义版本号或者使用默认的当前时间
description	否	String	分组描述信息

表5 paths参数说明
名称	是否必选	参数类型	说明
uri	是	Object	API访问地址，参考表6

表6 uri参数说明
名称	是否必选	参数类型	说明
method	是	Object	API访问方法，参考表7

表7 method参数说明
名称	是否必选	参数类型	说明
operationId	否	String	API的名称
description	否	String	API的描述信息
schemes	否	Object	API的请求协议对象数组定义，支持http、https
tags	否	Object	API标签对象数组定义
parameters	否	Object	请求参数对象数组定义，参考表前端parameters参数说明
responses	否	Object	响应定义，参考表9
security	否	Object	API的认证类型对象数组定义，参考表 security参数说明
x-apigateway-access-control	否	Object	API绑定的访问控制对象数组定义
x-apigateway-backend	否	Object	API的后端信息，参考表 x-apigateway-backend参数说明
x-apigateway-backend-policies	否	Object	API的策略后端信息，参考表 x-apigateway-backend-policies参数说明
x-apigateway-cors	否	Boolean	是否支持跨域
x-apigateway-match-mode	否	String	API的匹配方式
x-apigateway-ratelimit	否	String	API绑定的流量控制名称
x-apigateway-request-type	否	String	API的类型

表8 前端parameters参数说明
名称	是否必选	参数类型	说明
maximum	否	Float	参数为数值类型时，最大参数值
minimum	否	Float	参数为数值类型时，最小参数值
maxLength	否	Integer	参数为字符串类型时，参数的最大长度
minLength	否	Integer	参数为字符串类型时，参数的最小长度
pattern	否	String	参数值为正则匹配表达式
type	否	String	参数类型
default	否	String	参数默认值
description	否	String	参数描述信息
name	否	String	参数名称
in	否	String	参数位置，支持path、header、query、formData、body
required	否	Boolean	参数是否必需，参数位置为path时必需

表9 responses参数说明
名称	是否必选	参数类型	说明
default	否	Object	缺省响应，描述未定义的响应码
status_code	否	Object	响应状态码，值为响应对象，参考表11
x-apigateway-result-failure-sample	否	String	失败返回示例，描述API的异常返回信息
x-apigateway-result-normal-sample	否	String	正常响应示例，描述API的正常返回信息

**表10** security参数说明
名称	是否必选	参数类型	说明
apig-auth-type	否	Object	API的认证类型对象数组定义，为空数组 apig-auth-type支持： APP认证： apig-auth-app IAM认证：apig-auth-iam NONE：不填写

**表11** status code参数说明
名称	是否必选	参数类型	说明
description	否	String	响应描述信息
schema	否	Object	响应正文定义，参考表12

**表12** schema参数说明
名称	是否必选	参数类型	说明
description	否	String	BODY体描述
type	否	String	BODY体类型：FORM/STREAM（表单/字节流）

**表13** securityDefinitions参数说明
名称	是否必选	参数类型	说明
name	是	Object	自定义鉴权方式名称，参考表14

**表14** name参数说明
名称	是否必选	参数类型	说明
type	是	String	鉴权类型，支持apiKey
name	是	String	apiKey参数名称
in	是	String	apiKey参数位置
x-apigateway-auth-type	是	String	扩展鉴权类型，基于apiKey鉴权方式的扩展，网关自定义的鉴权方式，支持AppSigv1、IAM、IAM_NONE

**表15** x-apigateway-backend参数说明
名称	是否必选	参数类型	说明
type	是	String	API后端类型，支持HTTP、HTTP-VPC、MOCK
parameters	否	Object	后端参数对象数组定义，参考表后端parameters参数说明
backend_define	是	Object	API后端定义 backend_define支持： httpEndpoints，参考表后端httpEndpoints参数说明 httpVpcEndpoints，参考表后端httpVpcEndpoints参数说明 mockEndpoints，参考表后端mockEndpoints参数说明

**表16** x-apigateway-backend-policies参数说明
名称	是否必选	参数类型	说明
type	是	String	API后端类型，支持HTTP、HTTP-VPC、MOCK
name	否	String	后端策略名称
parameters	否	Object	后端参数对象数组定义，参考表后端parameters参数说明
backend_define	是	Object	API后端定义 backend_define支持： httpEndpoints，参考表后端httpEndpoints参数说明 httpVpcEndpoints，参考表后端httpVpcEndpoints参数说明 mockEndpoints，参考表后端mockEndpoints参数说明
conditions	是	Object	策略条件对象数组定义，参考表 conditions参数说明
effectMode	是	String	关联的策略组合模式，支持ANY、ALL

**表17** 后端parameters参数说明
名称	是否必选	参数类型	说明
name	是	String	参数名称，由字母、数字、下划线、连线、点组成，以字母开头，最长32字节 header位置的参数名称不区分大小写
value	是	String	参数值，当参数来源为REQUEST时，值为请求参数名称
in	是	String	参数位置，支持header、query、path
origin	是	String	参数映射来源，支持REQUEST、CONSTANT
description	否	String	参数含义描述

**表18** 后端httpEndpoints参数说明
名称	是否必选	参数类型	说明
address	是	String	后端服务地址，格式为：<域名或IP>:[port]
scheme	是	String	后端请求协议定义，支持http、https
method	是	String	后端请求方法，支持GET、POST、PUT、DELETE、HEAD、OPTIONS、PATCH、ANY
path	是	String	后端请求路径，支持路径变量
timeout	否	Integer	后端请求超时时间，单位毫秒，缺省值为5000，取值范围为1 ~ 60000
description	否	String	API后端描述

**表19** 后端httpVpcEndpoints参数说明
名称	是否必选	参数类型	说明
name	是	Array	VPC通道名称
scheme	是	String	后端请求协议定义，支持http、https
method	是	String	后端请求方法，支持GET、POST、PUT、DELETE、HEAD、OPTIONS、PATCH、ANY
path	是	String	后端请求路径，支持路径变量
timeout	否	Integer	后端请求超时时间，单位毫秒，缺省值为5000，取值范围为1 ~ 60000
host	否	String	VPC通道代理主机
description	否	String	API后端描述

**表20** 后端mockEndpoints参数说明
名称	是否必选	参数类型	说明
result-content	是	String	MOCK返回结果
description	否	String	API后端描述

**表21** conditions参数说明
名称	是否必选	参数类型	说明
type	是	String	策略条件类型，支持equal、enum、pattern
value	是	String	策略条件值
origin	是	String	策略条件输入来源，支持source、request
parameter	否	String	策略条件输入来源为request时，请求入参的名称

**表22** x-apigateway-access-controls参数说明
名称	是否必选	参数类型	说明
acl_name	否	Object	指定名称的访问控制策略，参考表 acl_name参数说明

**表23** acl_name参数说明
名称	是否必选	参数类型	说明
acl-type	是	String	访问控制行为，支持PERMIT、DENY
entity-type	是	String	访问控制对象，支持IP、DOMAIN
value	是	String	访问控制策略值，多个值以“,”间隔

**表24** x-apigateway-ratelimits参数说明
名称	是否必选	参数类型	说明
throttle_name	否	Object	指定名称的流控策略，参考表 throttle_name参数说明

**表25** throttle_name参数说明
名称	是否必选	参数类型	说明
api-limit	是	Integer	API访问次数限制
user-limit	否	Integer	用户访问次数限制
app-limit	否	Integer	应用访问次数限制
ip-limit	否	Integer	源IP访问次数限制
interval	是	Integer	流控策略时间周期
unit	是	String	流控策略时间周期单位，支持SECOND、MINUTE、HOUR、DAY
shared	否	Boolean	是否共享流控策略
special	否	Object	特殊流控策略对象数组定义，参考表 special参数说明

**表26** special参数说明
名称	是否必选	参数类型	说明
type	是	String	特殊流控策略类型，支持APP、USER
limit	是	Integer	访问次数
instance	是	String	特殊APP或USER的对象标识

请求消息样例：

{
	"swagger": "2.0",
	"info": {
		"description": "api group test",
		"title": "APIGroup_test",
		"version": "2019-09-12-17:38:10"
	},

	"paths": {
		"/test/{path}": {
			"get": {
				"security": [
					{
						"apig-auth-app": []
					}
				],
				"description": "api test",
				"schemes": [
					"https"
				],
				"operationId": "API_test",
				"parameters": [
					{
						"type": "string",
						"description": "header parameter",
						"name": "header",
						"in": "header",
						"required": true
					},
					{
						"type": "string",
						"description": "path parameter",
						"name": "path",
						"in": "path",
						"required": true
					},
					{
						"type": "number",
						"default": "123",
						"description": "query parameter",
						"name": "query",
						"in": "query"
					}
				],
				"responses": {
					"default": {
						"$ref": "#/responses/default"
					},
					"x-apigateway-result-failure-sample": "",
					"x-apigateway-result-normal-sample": "success"
				},
				"x-apigateway-backend": {
					"httpEndpoints": {
						"address": "1.1.1.1:443",
						"description": "",
						"method": "GET",
						"path": "/test/{path}",
						"scheme": "https",
						"timeout": 5000
					},
					"parameters": [
						{
							"description": "",
							"in": "HEADER",
							"name": "header",
							"origin": "REQUEST",
							"value": "header"
						},
						{
							"description": "",
							"in": "PATH",
							"name": "path",
							"origin": "REQUEST",
							"value": "path"
						},
						{
							"description": "",
							"in": "QUERY",
							"name": "query",
							"origin": "REQUEST",
							"value": "query"
						}
					],
					"type": "HTTP"
				},
				"x-apigateway-backend-policies": [
					{
						"conditions": [
							{
								"origin": "param",
								"parameter": "path",
								"type": "exact",
								"value": "path"
							},
							{
								"origin": "source",
								"parameter": "",
								"type": "",
								"value": "1.0.0.0/8"
							}
						],
						"effectMode": "ANY",
						"httpVpcEndpoints": {
							"method": "POST",
							"name": "VPC_n9ct",
							"path": "/",
							"scheme": "HTTPS",
							"timeout": 5000
						},
						"name": "policy_test",
						"type": "HTTP-VPC"
					}
				],
				"x-apigateway-cors": false,
				"x-apigateway-match-mode": "NORMAL",
				"x-apigateway-request-type": "public"
			}
		}
	},
	"responses": {
		"default": {
			"description": "response example"
		}
	},
	"securityDefinitions": {
		"apig-auth-app": {
			"type": "apiKey",
			"name": "Authorization",
			"in": "header",
			"x-apigateway-auth-type": "AppSigv1"
		},
		"apig-auth-iam": {
			"type": "apiKey",
			"name": "unused",
			"in": "header",
			"x-apigateway-auth-type": "IAM"
		}
	}
}

响应消息

**表27** 参数说明
名称	类型	说明
group_id	String	分组ID
success	Array	导入成功信息
failure	Array	导入失败信息

**表28** success参数说明
名称	类型	说明
id	String	导入成功的API ID
action	String	导入行为： update：表示更新API create：表示新建API
method	String	API请求方法
path	String	API请求路径

**表29** failure参数说明
名称	类型	说明
error_code	String	导入失败的错误码
error_msg	String	导入失败的错误信息
method	String	API请求方法
path	String	API请求路径

响应消息样例：

{
  "group_id": "27aa2317e3514c5bb5aab5587a5e50ea",
  "success": [
    {
      "id": "aea39194d8db46408be0174b0bd15931",
      "action": "create",
      "method": "GET",
      "path": "/test01"
    }
  ],
  "failure": [
    {
      "error_code": "APIG.2011",
      "error_msg": "Parameter value does not match the rules,parameterName:backend_type",
      "method": "GET",
      "path": "/test02"
    }
  ]
}

状态码

**表30** 返回消息说明
状态码	说明
200	OK
400	Bad Request
403	Forbidden
500	Server Internal Error

父主题： OpenAPI接口

上一篇：导入API到新分组

下一篇：自定义认证管理

意见反馈

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

有帮助没帮助

提供反馈

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

系统繁忙，请稍后重试

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

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

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

字符长度不能超过500

直接提交取消