文档

DescribeApiDoc - 查询API说明文档

更新时间:

查询指定API的服务说明文档。

接口说明

  • 此功能面向调用 API 的用户,指定的 API 必须是发布到运行环境,且 Visibility=PUBLIC 的 API 或者被授权的 Visibility=PRIVATE 的 API
  • 若您是调用 API 的用户,该接口返回您指定的 API 的服务信息及参数定义等详情信息。
  • 若您是开放 API 的用户,那么调用该接口可以查看当前指定 API 在指定环境中运行的定义,可能与您现在修改中的 API 定义不同,是真正在环境中生效的定义。
  • 若您是开放 API 的用户,由于该接口面向 API 调用者鉴权,所以您需要确认该 API 为 PUBLIC 类型或者您的相关 APP 已被授权。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
apigateway:DescribeApiDocRead
  • 全部资源
    *

请求参数

名称类型必填描述示例值
GroupIdstring

指定的分组编号

123
StageNamestring

环境名称,可选值:

  • RELEASE: 线上
  • TEST: 测试

若不传入,则默认为 release。

RELEASE
ApiIdstring

指定的 API 编号

3b81fd160f5645e097cc8855d75a1cf6

返回参数

名称类型描述示例值
object
ApiIdstring

API 编号

b24be7e59a104e52bffbf432cc9272af
ResultTypestring

返回类型

JSON
DisableInternetboolean
  • 设置 DisableInternettrue, 仅支持内网调用 API。
  • 设置 DisableInternetfalse, 则不限制调用。创建 API 时默认为 false。
true
ResultSamplestring

返回示例

{\n \"status\": 0,\n \"data\": {\n \"count\": 1,\n \"list\": [\n \"352\"\n ]\n },\n \"message\": \"success\"\n}
RegionIdstring

API 分组所在的地域 ID

cn-hangzhou
ForceNonceCheckboolean
  • 设置 ForceNonceChecktrue, 请求时强制检查 X-Ca-Nonce,这个是请求的唯一标识,一般使用 UUID 来标识。API 网关收到这个参数后会校验这个参数的有效性,同样的值,15 分内只能被使用一次。可以有效防止 API 的重放攻击。

  • 设置 ForceNonceCheckfalse,则不检查。创建 API 时默认为 false。

true
Visibilitystring

可见性,取值为:PUBLICPRIVATE,分别表示公开、私有

PUBLIC
FailResultSamplestring

后端服务失败返回应答的示例

{"errorCode":"fail","errorMessage":"param invalid"}
AuthTypestring

安全认证方式,取值为:APP、ANONYMOUS,分别表示阿里云 APP、匿名

APP
RequestIdstring

请求 ID

F253FB5F-9AE1-5DDA-99B5-46BE00A3719E
GroupIdstring

API 分组编号

f51d08c5b7c84342905544ebaec26d35
GroupNamestring

API 分组名称

会员时代交易服务
Descriptionstring

API 描述

领克数字商城OMS-UAT
DeployedTimestring

发布时间

2022-07-13T16:00:33Z
StageNamestring

环境名称,可选值:

  • RELEASE: 线上
  • TEST: 测试
RELEASE
ApiNamestring

API 名称

获取关键词二维码地址
RequestConfigobject

由 RequestConfig 组成的格式,返回 API 前端定义信息

RequestPathstring

API path,比如 API 的完全地址为http://api.a.com:8080/object/add?key1=value1&key2=value2,path 是指/object/add这一部分。

/api/billing/test/[type]
RequestHttpMethodstring

HTTP Method,取值为:GET、POST、DELETE、PUT、HEADER、TRACE、PATCH、CONNECT、OPTIONS。

POST
BodyFormatstring

RequestMode 值为 MAPPING 时有效。

POST/PUT 请求时,表示数据以何种方式传递给服务器,取值为:FORMSTREAM,分别表示表单形式(k-v 对应)、字节流形式。

STREAM
RequestModestring

入参请求的模式,取值为:

  • MAPPING:入参映射(过滤未知参数)

  • PASSTHROUGH:入参透传

  • MAPPING_PASSTHROUGH:入参映射(透传未知参数)

MAPPING
PostBodyDescriptionstring

Body 描述

fwefwef
RequestProtocolstring

API 支持的协议类型,可以多选,多选情况下以英文逗号隔开,如:”HTTP,HTTPS”,取值为:HTTP、HTTPS。

HTTP
ErrorCodeSamplesobject []

后端服务返回的错误码示例

Codestring

错误码

Error
Messagestring

错误消息

error message
Descriptionstring

错误码描述

未授权
RequestParametersobject []

由 RequestParameter 组成的数组格式,返回 API 中前端入参信息项

JsonSchemestring

JSON scheme

{}
MaxValuelong

最大值

200
ArrayItemsTypestring

数组元素的类型

String
MinValuelong

最小值

123456
DocShowstring

文档可见,取值为:PUBLICPRIVATE

PUBLIC
MaxLengthlong

最大长度

123456
DefaultValuestring

默认值

20
ApiParameterNamestring

API 参数名称

Length
EnumValuestring

ParameterType=Int、Long、Float、Double 或 String,允许输入的散列值,不同的值用英文的逗号分隔,形如:1,2,3,4,9 或 A,B,C,E,F。

boy,girl
DemoValuestring

示例值

20
Requiredstring

是否必填

OPTIONAL
Descriptionstring

描述信息

参数说明
ParameterTypestring

参数类型

String
RegularExpressionstring

ParameterType=String,参数验证(正则表达式)

xxx
MinLengthlong

最小长度

2
DocOrderinteger

文档中顺序

0
Locationstring

参数位置,取值为:BODY、HEAD、QUERY、PATH

HEAD

示例

正常返回示例

JSON格式

{
  "ApiId": "b24be7e59a104e52bffbf432cc9272af",
  "ResultType": "JSON",
  "DisableInternet": true,
  "ResultSample": "{\\n  \\\"status\\\": 0,\\n  \\\"data\\\": {\\n    \\\"count\\\": 1,\\n    \\\"list\\\": [\\n      \\\"352\\\"\\n    ]\\n  },\\n  \\\"message\\\": \\\"success\\\"\\n}",
  "RegionId": "cn-hangzhou",
  "ForceNonceCheck": true,
  "Visibility": "PUBLIC",
  "FailResultSample": "{\"errorCode\":\"fail\",\"errorMessage\":\"param invalid\"}",
  "AuthType": "APP",
  "RequestId": "F253FB5F-9AE1-5DDA-99B5-46BE00A3719E",
  "GroupId": "f51d08c5b7c84342905544ebaec26d35",
  "GroupName": "会员时代交易服务",
  "Description": "领克数字商城OMS-UAT",
  "DeployedTime": "2022-07-13T16:00:33Z",
  "StageName": "RELEASE",
  "ApiName": "获取关键词二维码地址",
  "RequestConfig": {
    "RequestPath": "/api/billing/test/[type]",
    "RequestHttpMethod": "POST",
    "BodyFormat": "STREAM",
    "RequestMode": "MAPPING",
    "PostBodyDescription": "fwefwef",
    "RequestProtocol": "HTTP",
    "EscapePathParam": true
  },
  "ErrorCodeSamples": {
    "ErrorCodeSample": [
      {
        "Code": "Error",
        "Message": "error message",
        "Description": "未授权"
      }
    ]
  },
  "RequestParameters": {
    "RequestParameter": [
      {
        "JsonScheme": "{}",
        "MaxValue": 200,
        "ArrayItemsType": "String",
        "MinValue": 123456,
        "DocShow": "PUBLIC",
        "MaxLength": 123456,
        "DefaultValue": "20",
        "ApiParameterName": "Length",
        "EnumValue": "boy,girl",
        "DemoValue": "20",
        "Required": "OPTIONAL",
        "Description": "参数说明",
        "ParameterType": "String",
        "RegularExpression": "xxx",
        "MinLength": 2,
        "DocOrder": 0,
        "Location": "HEAD"
      }
    ]
  }
}

错误码

访问错误中心查看更多错误码。

变更历史

变更时间变更内容概要操作
2024-05-27OpenAPI 返回结构发生变更看变更集
变更项变更内容
出参OpenAPI 返回结构发生变更
2023-07-10OpenAPI 返回结构发生变更看变更集
变更项变更内容
出参OpenAPI 返回结构发生变更
  • 本页导读 (1)