search

awslabs / aws-api-gateway-developer-portal

A Serverless Developer Portal for easily publishing and cataloging APIs
Apache License 2.0
932 stars 402 forks source link

Api Gateway does not support nor ignore "example" tags in swagger #571

Open supertick opened 2 years ago

supertick commented 2 years ago

Hello, We currently deploy our interface into aws api gateway with a swagger 2.0 json file. While trying to provide documentation in examples - we get the following from a terraform deployment.

[2022-06-27T16:17:18.951Z] ╷ [2022-06-27T16:17:18.951Z] │ Error: error updating API Gateway specification: BadRequestException: Errors found during import: [2022-06-27T16:17:18.951Z] │ Unable to create model for 'SearchQuery': Invalid model specified: Validation Result: warnings : [], errors : [Invalid model schema specified. Unsupported keyword(s): ["example"]] [2022-06-27T16:17:18.951Z] │ Unable to put method 'POST' on resource at path '/search': Invalid model identifier specified: null [2022-06-27T16:17:18.951Z] │ Additionally, these warnings were found: [2022-06-27T16:17:18.951Z] │ Reference to model 'SearchQuery' not found. Ignoring. [2022-06-27T16:17:18.951Z] │ which is preventing our deployment. The "example" is defined in both swagger 2.0 and 3.0 You can find documentation here - https://swagger.io/docs/specification/2-0/adding-examples/

I've tried both 2.0 and 3.0 formats - but neither work.

The gateway would just need to ignore these tags to "support" them. It seems silly we have to exclude meaningful documentation for the aws bug. Cheers, Greg.

martinabrahams commented 2 years ago

I agree, I'm creating my API Gateway from a generated swagger definition using CDK which already contains the examples are they're being dropped from the spec.

JoshuaKemmerer commented 6 months ago

I'm having this same issue. I don't understand why they don't ignore the "examples" tag. This is very disappointing