feat(gatewayresponses): add support for API Gateway Responses

[chrisoverzero]

This is a WIP. Remaining:

1. Documentation
2. Example
3. Edge Cases Which Will Be Pointed Out to Me, I'm Sure???

Issue #, if available:

#815

Description of changes:

Added new property GatewayResponses to AWS::Serverless::API. This translates to x-amazon-apigateway-gateway-responses in the generated Swagger with some convenience transformations applied for SAMier syntax.

Description of how you validated changes:

In addition to the present test suite, ran a company project through the translator. It deployed and worked correctly. (Then I reluctantly took it back down.)

Checklist:

• Write/update tests
• make pr passes
• Update documentation
• Create example

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[chrisoverzero]

Documentation is added. I tried to match house style, but lemme know if it's n-not?

I intend to have an example committed today, but Day Job may interfere.

[chrisoverzero]

OK, I think we in it.

I am the furthest thing from a professional Python developer, so please do let me know where I've fallen down.

[codecov-io]

Codecov Report

Merging #841 into develop will decrease coverage by 0.04%.
The diff coverage is 92.3%.

@@             Coverage Diff             @@
##           develop     #841      +/-   ##
===========================================
- Coverage    94.58%   94.54%   -0.05%     
===========================================
  Files           67       67              
  Lines         2865     2933      +68     
  Branches       519      538      +19     
===========================================
+ Hits          2710     2773      +63     
- Misses          83       85       +2     
- Partials        72       75       +3

Impacted Files	Coverage Δ
samtranslator/model/sam_resources.py	95.5% <ø> (ø)	⬆️
samtranslator/model/apigateway.py	97.72% <100%> (+0.5%)	⬆️
samtranslator/swagger/swagger.py	97.56% <100%> (+0.09%)	⬆️
samtranslator/plugins/globals/globals.py	100% <100%> (ø)	⬆️
samtranslator/model/api/api_generator.py	94.23% <76.19%> (-2.03%)	⬇️
samtranslator/translator/translator.py	99.09% <0%> (+0.06%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 972b610...4d18722. Read the comment docs.

[brettstack]

This is really awesome. Thank you so much for doing this!

[brettstack]

Looking good! I haven't yet reviewed the test input/output.

[chrisoverzero]

Awesome. Thanks so much. I'm past EoD here in my time zone, but I'll jump on these in the morning.

[chrisoverzero]

Apologies for the force pushes -- trying to get the merge conflict resolved.

This is now caught up with current feedback.

[brettstack]

I just have a couple of requests:

1. The comment about not allowing String for StatusCode. I think API Gateway will accept a String, and if that's the case we shouldn't disallow its use in SAM (i.e we should allow both number and string)
2. Could you add a test which has multiple GatewayResponses? All tests appear to just have a single UNAUTHORIZED GatewayResponse. You can update one of your existing tests to just include a second one.

[brettstack]

Ship!

[carlnordenfelt]

Really glad to see this merged! Thanks @chrisoverzero for picking this up!

@brettstack @keetonian do you guys have any idea when this will be released? I'm in dire need of this to avoid having to define the entire API myself at the moment.

[keetonian]

@carlnordenfelt We're working on it now. We just cut a release branch: https://github.com/awslabs/serverless-application-model/tree/release/v1.11.0

We should be able to release this soon, barring any unforeseen issues with the new features.