Documentation?

[jsorge]

I'm just getting started with this, and it's looking like a great tool! I am wondering about documentation for the x-amazon-apigateway-auth and x-amazon-apigateway-integration objects that get injected into Swagger to hook up things like Lambda functions. Is there anywhere these are documented for reference? When I tried to put them into my JSON file and import into the API gateway I got lots of errors and am not sure how to proceed.

For now I'm just going to hook things up manually. This tool looks like a great start. Thanks!

[midwire]

+1. Would love to be notified when documentation for the extensions is published. Particularly on how to map to Request Models in the Method Request. I am thinking it is some kind of syntax with $ref:, but cannot find an example so far.

Again, awesome tool! Can't wait for the docs.

[rpgreen]

We have people working on it and hope to have this available soon. Thanks for your patience

[gliderjockey]

+1 on documentation.

[koxon]

+1. Kind of hard right now to map all properties in x-amazon-apigateway-integration

[apaatsio]

Better documentation of the Swagger extensions would be appreciated.

[midwire]

Just from my own trial and error experience, I found the following to allow us to map JSON objects for POST and PUT requests:

        requestTemplates:
          application/json: "$input.json('$.event')"

Where the POST request sends a JSON object something like this:

"event": {
  "name":"whatever",
  ...
}

This works. However, I'm not convinced it is the complete solution. It does end up passing the JSON arguments with the request.

Lastly, I want to give kudos to @rpgreen for writing the tool. I am quite disappointed, however, with the lack of documentation (still, after weeks of waiting) and the level of support from a company like Amazon, for this tool, is far from adequate.

Come on guys! Get some docs put together already. We all realize there is always a critical path and time is limited, but this is getting ridiculous!

[rpgreen]

Hi folks - sorry about the delay - we are actively working on better documentation.

In the meantime, maybe you can help us focus the documentation efforts. What exactly are you trying to achieve and where are you getting stuck? What kind of examples would you like to see? Would you prefer specification-style documentation or walkthroughs? Which parts of the tool are most confusing?

As a side note, the Swagger extensions are simply an analog of the concepts in our REST API. If you haven't already, I would highly recommend reading the API docs as well as the service documentation. If you are still having issues then please let us know so we can update our core docs as well.

Another hint on getting up to speed with the importer/API is to use a browser debugger to inspect how the web console uses the API.

Again, thanks for your patience and any feedback on how to improve the documentation would be much appreciated.

[midwire]

Hey Ryan, for me it would be examples containing how to map values. Various requestTemplates and responseTemplatesexamples would be quite helpful.

      x-amazon-apigateway-integration:
        type: "http"
        uri: "http://50fd882d.ngrok.io/api/{version}/events"
        httpMethod: "POST"
        requestParameters:
          integration.request.path.version: "method.request.path.version"
          integration.request.querystring.user_auth: "method.request.querystring.user_auth"
        requestTemplates:
          application/json: "$input.json('$.event')" # Examples for this would be great.
        responses:
          2\d{2}:
            statusCode: "200"
          default:
            statusCode: "400"
            responseTemplates:
              application/json: "json 400 response template" # Examples for this would be great.

It took me a long time to figure out how to map the JSON for a POST, and I'm still not sure I'm doing it correctly. Docs like this are less than helpful: http://docs.aws.amazon.com/apigateway/api-reference/resource/integration/#requestTemplates

{
  "type" : "String",
  "httpMethod" : "String",
  "uri" : "String",
  "credentials" : "String",
  "requestParameters" : {
    "String" : "String"
  },
  "requestTemplates" : {
    "String" : "String" # This doesn't help
  },
  "cacheNamespace" : "String",
  "cacheKeyParameters" : [ "String" ]
}

I've probably been looking in the wrong place.

Again, thank you for writing the tool. It will surely prove to be quite useful to my company as using the web-console for large APIs is intractable.

[optimuspaul]

Any progress?

[koxon]

Working by example being the only way at the moment, I thought to share my
swaggerhub file.

If you're looking for a working example that uses:

• API GW -> Lambda with standard exec roles
• Cognito -> API GW -> Lambda with Cognito roles. (User's credentials).
• API GW -> Proxy API (http://orchestrate.io)
• A bunch of input/output mapping templates
• Custom error codes matching Lambda exception messages.

Then check our API:
https://swaggerhub.com/api/koxon/api.user.sportarchive.tv/0.6

If you are using Python Lambda code,
we created a little framework to run your Python functions locally and Mock
the Lambda Event and Context variable.
It also inject a Cognito IdentityId if you want. It's all done using a
simple Makefile.
See: https://github.com/sportarchive/aws-lambda-python-local

Hope this will help

cheers
@koxon
ᐧ

On Wed, Dec 16, 2015 at 1:05 PM, Paul DeCoursey notifications@github.com
wrote:

Any progress?

—
Reply to this email directly or view it on GitHub
#30 (comment)
.

Nicolas Menciere
Co-Founder and CTO
Sport Archive Inc.

[rpgreen]

Very nice!

[rpgreen]

Swagger/OpenAPI import is now generally available in the API Gateway REST API, the AWS CLI and all AWS SDKs. You can also import and export Swagger definitions using the API Gateway console. This release addresses many of the open issues and feedback in this repository.

I would encourage you to migrate your workflow to the standard AWS tools. aws-apigateway-importer will receive minimal support from the API Gateway team going forward.

Any feedback or issues with the new importer should be directed to the official API Gateway forums.

Thanks,
Ryan