OpenAPI Import Error Improvements/Debugging

0

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?

1 Answer
0

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

AWS
answered 12 days ago
  • Thanks for the reply and suggestions.

    Question 1: Is there a better way to debug errors with importing an OpenAPI specification into API Gateway ? So I tried the CloudWatch logs approach, and while the CLI import still errors out, nothing is logged into CloudWatch for the API Gateway when this happens. And this is after turning on the everything for the logs, error, info, full request and response. It does not appear to log any additional details when an import fails to CloudWatch.

    We do validate our OpenAPI spec already, which is the frustrating part as our document is compliant to the OpenAPI standards and yet fails in Gateway either due to missing features or this unclear error.

    Question 3: Can CLI be forced to return the exception as a JSON payload so it is useable within CI reporting ? I appreciate the tips here, but I already tried them to no success. Here's information from my terminal attempting to do this:

  • api-specs on ☁️  (us-east-1)
    ❯ aws --version
    aws-cli/2.17.10 Python/3.11.9 Darwin/22.6.0 source/arm64
    
    api-specs  on ☁️  (us-east-1)
    ❯ export AWS_DEFAULT_OUTPUT=json
    
    api-specs on ☁️  (us-east-1)
    ❯ cat ~/.aws/config
    ... SNIPPED...
    [default]
    region = us-east-1
    output = json
    
    api-specs on ☁️  (us-east-1)
    ❯ aws --output json --no-paginate apigateway put-rest-api --rest-api-id $GATEWAY_ID --mode overwrite --body 'fileb://./dist/api/swagger/builds/modernize-api-v1.yaml'
    
    An error occurred (BadRequestException) when calling the PutRestApi operation: Errors found during import:
    

    If it is supposed to work and turn the BadRequestException into a JSON response, the CLI seems to be bugged here

You are not logged in. Log in to post an answer.

A good answer clearly answers the question and provides constructive feedback and encourages professional growth in the question asker.

Guidelines for Answering Questions