文档首页/ API网关 APIG/ API参考/ 共享版API（仅存量用户使用）/ OpenAPI接口/ 导入API到新分组

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

导入API到新分组

功能介绍

通过导入的swagger文件创建新分组和新API。swagger文件支持json以及yaml格式。

URI

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

表1
请求方法	URI
POST	/v1.0/apigw/openapi

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

表2 参数说明
参数	参数位置	是否必选	类型	说明
extend_mode	query	否	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、FUNCTION、MOCK
parameters	否	Object	后端参数对象数组定义，参考表后端parameters参数说明
backend_define	是	Object	API后端定义 backend_define支持： httpEndpoints，参考表后端httpEndpoints参数说明 httpVpcEndpoints，参考表后端httpVpcEndpoints参数说明 functionEndpoints，参考表后端functionEndpoints参数说明 mockEndpoints，参考表后端mockEndpoints参数说明

**表16** x-apigateway-backend-policies参数说明
名称	是否必选	参数类型	说明
type	是	String	API后端类型，支持HTTP、HTTP-VPC、FUNCTION、MOCK
name	否	String	后端策略名称
parameters	否	Object	后端参数对象数组定义，参考表后端parameters参数说明
backend_define	是	Object	API后端定义 backend_define支持： httpEndpoints，参考表后端httpEndpoints参数说明 httpVpcEndpoints，参考表后端httpVpcEndpoints参数说明 functionEndpoints，参考表后端functionEndpoints参数说明 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** 后端functionEndpoints参数说明
名称	是否必选	参数类型	说明
function-urn	是	String	函数URN地址
version	是	String	函数版本
invocation-type	是	String	函数调用类型，支持async、sync
timeout	否	Integer	函数超时时间，单位毫秒，缺省值为5000，取值范围为1 ~ 60000
description	否	String	API后端描述

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

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

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

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

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

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

**表27** 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"
		}
	}
}

响应消息

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

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

**表30** 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"
    }
  ]
}

状态码

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

父主题： OpenAPI接口

上一篇：批量导出API

下一篇：导入API到已有分组

导入API到新分组

功能介绍

URI

请求消息

响应消息

状态码

相关文档

您对此文档页面的整体评价？