OpenAPI Import Error Improvements/Debugging

Question

Ok I have to ask, is there a better way to debug errors with importing an OpenAPI specification into API Gateway? Because this error is.. less than helpful. I'd even go as far to say it's making debugging the issue harder not easier. The PR with changes to our OpenAPI specification doesn't even include changes for the model it is flagging, and yet suddenly there is an issue with someone that wasn't touched? How does that make sense?

```
An error occurred (BadRequestException) when calling the PutRestApi operation: Errors found during import:
        Unable to create model for 'ClientProfile': Invalid model specified: Validation Result: warnings : [], errors : [Model reference must be in canonical form]
```

Side note, can the CLI be forced to return this exception as a JSON payload so it is useable within CI reporting?

Shubham_S · Answer

Hello,

Please allow me to answer your questions one by one below.

Question 1: Is there a better way to debug errors with importing an OpenAPI specification into API Gateway ?

Answer :  To debug errors when importing an OpenAPI specification into API Gateway, consider the following steps.
                 
A) Check Cloud watch logs: Enable logging for your API Gateway [1] and review the logs in CloudWatch to identify any errors or warning during the execution process. This can provide insights into what might be going wrong .
           
B) Validate OpenAPI Specification: Use tools to validate your OpenAPI specification [2] to ensure it adheres to the required standards and doesn’t contain any error.
You can use below tool to parses and validates a Swagger/OpenAPI 2.0 or an OpenAPI 3.x definition [3].

[1] https://repost.aws/knowledge-center/api-gateway-cloudwatch-logs

[2] https://validator.swagger.io/

[3] https://www.jsonschemavalidator.net/

——————————————————————————————

Question 2: The PR with changes to our OpenAPI specification doesn't even include changes for the model it is flagging, and yet suddenly there is an issue with someone that wasn't touched .

Answer: To look into the above issue, we require details that are non-public information. Please open a support case with AWS using the following link.

Link : https://support.console.aws.amazon.com/support/home#/case/create

——————————————————————————————

Question 3: Can CLI be forced to return the exception as a JSON payload so it is useable within CI reporting ?

Answer: Yes, AWS CLI can be forced to return output in 3 formats i.e. JSON, Text and Tables. There are 3 ways to setup the output format.

A) Using the output option in a named profile in the config file.

B) Using the AWS_DEFAULT_OUTPUT environment variable.

C) Using the --output option on the command line

Please refer the below link to setup the format of AWS CLI output as JSON.

Link: https://docs.aws.amazon.com/cli/v1/userguide/cli-usage-output-format.html

OpenAPI Import Error Improvements/Debugging

Relevant content