DescribeApiDoc API Reference & Response Fields - API Gateway - Alibaba Cloud - API Gateway

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.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

apigateway:DescribeApiDoc

get

*ApiGroup

acs:apigateway:{#regionId}:{#accountId}:apigroup/{#GroupId}

None

Request parameters

Parameter	Type	Required	Description	Example
GroupId	string	No	The ID of the API group.	123
StageName	string	No	The environment name. Valid values: RELEASE TEST If this parameter is not specified, the default value RELEASE is used.	RELEASE
ApiId	string	Yes	The ID of the API.	3b81fd160f5645e097cc8855d75a1cf6

Response elements

Element	Type	Description	Example
	object
ApiId	string	The ID of the API.	b24be7e59a104e52bffbf432cc9272af
ResultType	string	The return value type.	JSON
DisableInternet	boolean	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
ResultSample	string	The sample response.	{\n \"status\": 0,\n \"data\": {\n \"count\": 1,\n \"list\": [\n \"352\"\n ]\n },\n \"message\": \"success\"\n}
RegionId	string	The region ID of the API group.	cn-hangzhou
ForceNonceCheck	boolean	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
Visibility	string	Indicates whether the API is public. Valid values: PUBLIC and PRIVATE.	PUBLIC
FailResultSample	string	The sample error response from the backend service.	{"errorCode":"fail","errorMessage":"param invalid"}
AuthType	string	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
RequestId	string	The ID of the request.	F253FB5F-9AE1-5DDA-99B5-46BE00A3719E
GroupId	string	The ID of the API group.	f51d08c5b7c84342905544ebaec26d35
GroupName	string	The name of the API group.	Member-era transaction service
Description	string	The API description.	Lynk & Co digital mallOMS-UAT
DeployedTime	string	The publishing time.	2022-07-13T16:00:33Z
StageName	string	The name of the runtime environment. Valid values: RELEASE TEST	RELEASE
ApiName	string	The name of the API	Obtains the QR code URL for a keyword.
RequestConfig	object	The returned API frontend definition. It is an array consisting of RequestConfig data.
RequestPath	string	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]
RequestHttpMethod	string	The HTTP method used to make the request. Valid values: GET, POST, DELETE, PUT, HEADER, TRACE, PATCH, CONNECT, and OPTIONS.	POST
BodyFormat	string	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
RequestMode	string	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
PostBodyDescription	string	The description of the request body.	fwefwef
RequestProtocol	string	The protocol type supported by the API. Valid values: HTTP and HTTPS. Separate multiple values with commas (,), such as "HTTP,HTTPS".	HTTP
EscapePathParam	boolean	Whether to escape the Path parameter, if true, the [param] on the Path will be treated as a regular character.	true
ErrorCodeSamples	object
ErrorCodeSample	array<object>	The sample error codes returned by the backend service.
	object	The sample error codes returned by the backend service.
Code	string	The returned error code.	Error
Message	string	The returned error message.	error message
Description	string	The error description.	Unauthorized
RequestParameters	object
RequestParameter	array<object>	The returned frontend input parameters in the API. It is an array consisting of RequestParameter data.
	object	The returned frontend input parameters in the API. It is an array consisting of RequestParameter data.
JsonScheme	string	JSON scheme	{}
MaxValue	integer	The maximum value.	200
ArrayItemsType	string	The type of the array element.	String
MinValue	integer	The minimum value.	123456
DocShow	string	Indicates whether the document is public. Valid values: PUBLIC and PRIVATE.	PUBLIC
MaxLength	integer	The maximum length.	123456
DefaultValue	string	The default value.	20
ApiParameterName	string	The name of the parameter in the API request.	Length
EnumValue	string	The hash values that are supported when ParameterType is set to Int, Long, Float, Double, or String. Separate values with commas (,). Examples: 1,2,3,4,9 and A,B,C,E,F.	boy,girl
DemoValue	string	The example value.	20
Required	string	Indicates whether the parameter is required.	OPTIONAL
Description	string	The parameter description.	Parameter description
ParameterType	string	The data type of the parameter.	String
RegularExpression	string	The regular expression that is used for parameter validation when ParameterType is set to String.	xxx
MinLength	integer	The minimum length.	2
DocOrder	integer	The order in which the parameter is sorted in the document.	0
Location	string	The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD

Examples

Success response

JSON format

{
  "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-era transaction service",
  "Description": "Lynk & Co digital mallOMS-UAT",
  "DeployedTime": "2022-07-13T16:00:33Z",
  "StageName": "RELEASE",
  "ApiName": "Obtains the QR code URL for a keyword.",
  "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": "Unauthorized"
      }
    ]
  },
  "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": "Parameter description",
        "ParameterType": "String",
        "RegularExpression": "xxx",
        "MinLength": 2,
        "DocOrder": 0,
        "Location": "HEAD"
      }
    ]
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.