All Products
Search
Document Center

API Gateway:DescribeApiDoc

Last Updated:Mar 01, 2024

Queries the documentation of an API.

Operation description

  • For API callers, the specified API must be a public or authorized private API that has been published to a runtime environment.
  • When you call this operation as an API caller, the service information, parameter definitions, and other details of the API you specify are returned.
  • When you call this operation as an API provider, the definition of the specified API running in the specified runtime environment is returned. The returned definition takes effect in the runtime environment, and may be different from the definition of the API you modify.
  • Before you call this operation as an API provider, ensure that the API to be queried is a public one or that your application has been authorized to call the API, because authentication on API callers is required.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
apigateway:DescribeApiDocRead
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
GroupIdstringNo

The ID of the API group.

123
StageNamestringNo

The environment to which the API is published. Valid values:

  • RELEASE
  • TEST

If this parameter is not specified, the default value is used, which is RELEASE.

RELEASE
ApiIdstringYes

The ID of the API.

3b81fd160f5645e097cc8855d75a1cf6

Response parameters

ParameterTypeDescriptionExample
object
ApiIdstring

The ID of the API.

b24be7e59a104e52bffbf432cc9272af
ResultTypestring

The return value type.

JSON
DisableInternetboolean
  • Specifies whether to set DisableInternet to true to limit API calls to within the VPC.
  • If you set DisableInternet to false, the limit is lifted. The default value is false when you create an API.
true
ResultSamplestring

The sample response.

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

The region ID of the API group.

cn-hangzhou
ForceNonceCheckboolean
  • Specifies whether to set ForceNonceCheck to true to force the check of X-Ca-Nonce during the request. This is the unique identifier of the request and is generally identified by UUID. After receiving this parameter, API Gateway verifies the validity of this parameter. The same value can be used only once within 15 minutes. This helps prevent replay attacks.
  • If you set ForceNonceCheck to false, the check is not performed. The default value is false when you create an API.
true
Visibilitystring

Indicates whether the API is public. Valid values: PUBLIC and PRIVATE.

PUBLIC
FailResultSamplestring

The sample error response from the backend service.

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

The security authentication method. Valid values: APP, ANONYMOUS, and APPOPENID, indicating respectively Alibaba Cloud application authentication, anonymous authentication, and third-party OpenID Connect account authentication.

APP
RequestIdstring

The ID of the request.

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

The ID of the API group.

f51d08c5b7c84342905544ebaec26d35
GroupNamestring

The name of the API group.

Member Age Transaction Service
Descriptionstring

The API description.

Lynk\&Co Digital Mall OMS-UAT
DeployedTimestring

The publishing time.

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

The name of the runtime environment. Valid values:

  • RELEASE
  • TEST
RELEASE
ApiNamestring

The name of the API

ObtainKeywordQRCodeAddress
RequestConfigobject

The returned API frontend definition information. It is an array consisting of RequestConfig data.

RequestPathstring

The API request path. If the complete API URL is http://api.a.com:8080/object/add?key1=value1&key2=value2, the API request path is /object/add .

/api/billing/test/[type]
RequestHttpMethodstring

The HTTP method used to make the request. Valid values: GET, POST, DELETE, PUT, HEADER, TRACE, PATCH, CONNECT, and OPTIONS.

POST
BodyFormatstring

This parameter takes effect only when the RequestMode parameter is set to MAPPING.********

The server data transmission method used for POST and PUT requests. Valid values: FORM and STREAM. FORM indicates that data in key-value pairs is transmitted as forms. STREAM indicates that data is transmitted as byte streams.

STREAM
RequestModestring

The request mode. Valid values:

  • MAPPING: Parameters are mapped. Unknown parameters are filtered out.
  • PASSTHROUGH: Parameters are passed through.
  • MAPPING_PASSTHROUGH: Parameters are mapped. Unknown parameters are passed through.
MAPPING
PostBodyDescriptionstring

The description of the request body.

fwefwef
RequestProtocolstring

The protocol type supported by the API. Valid values: HTTP and HTTPS. Separate multiple values with commas (,), such as "HTTP,HTTPS".

HTTP
ErrorCodeSamplesobject []

The sample error codes returned by the backend service.

Codestring

The returned error code.

Error
Messagestring

The returned error message.

error message
Descriptionstring

The description of the error code.

Unauthorized
RequestParametersobject []

The returned frontend input parameters in the API. It is an array consisting of RequestParameter data.

JsonSchemestring

JSON scheme

{}
MaxValuelong

The maximum value.

200
ArrayItemsTypestring

The type of the array element.

String
MinValuelong

The minimum value.

123456
DocShowstring

Indicates whether the document is public. Valid values: PUBLIC and PRIVATE.

PUBLIC
MaxLengthlong

The maximum length.

123456
DefaultValuestring

The default value.

20
ApiParameterNamestring

The name of the parameter in the API request.

Length
EnumValuestring

The hash values that can be specified if the ParameterType parameter is set to Int, Long, Float, Double, or String. Separate multiple hash values with commas (,). Examples: 1,2,3,4,9 and A,B,C,E,F.

boy,girl
DemoValuestring

The example value.

20
Requiredstring

Indicates whether the parameter is required.

OPTIONAL
Descriptionstring

The description.

Parameters
ParameterTypestring

The data type of the parameter.

String
RegularExpressionstring

The regular expression that is used to validate the parameter if the ParameterType parameter is set to String.

xxx
MinLengthlong

The minimum length.

2
DocOrderinteger

The order in which the parameter is sorted in the document.

0
Locationstring

The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.

HEAD

Examples

Sample success responses

JSONformat

{
  "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": "Member Age Transaction Service\n",
  "Description": "Lynk\\&Co Digital Mall OMS-UAT\n",
  "DeployedTime": "2022-07-13T16:00:33Z",
  "StageName": "RELEASE",
  "ApiName": "ObtainKeywordQRCodeAddress\n",
  "RequestConfig": {
    "RequestPath": "/api/billing/test/[type]",
    "RequestHttpMethod": "POST",
    "BodyFormat": "STREAM",
    "RequestMode": "MAPPING",
    "PostBodyDescription": "fwefwef",
    "RequestProtocol": "HTTP"
  },
  "ErrorCodeSamples": {
    "ErrorCodeSample": [
      {
        "Code": "Error",
        "Message": "error message",
        "Description": "Unauthorized\n"
      }
    ]
  },
  "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": "Parameters\n",
        "ParameterType": "String",
        "RegularExpression": "xxx",
        "MinLength": 2,
        "DocOrder": 0,
        "Location": "HEAD"
      }
    ]
  }
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2023-07-10The response structure of the API has changedsee changesets
Change itemChange content
Output ParametersThe response structure of the API has changed.