I have the same task of using the serverless framework to create a proxy for S3 service. To be honest, it’s harder than expected because the integration between formats is not fully clear:
- API Gateway works with swagger specification
- The API Gateway also works with Cloud Formation templates
- Cloud Formation templates accept embedded swagger specification
Initially, I started from building the swagger specification and trying to import it in the API Gateway. Then, I imagined, extending it with the specific extensions from the Amazon Console UI. It didn’t work, because the validation on import is strict and the errors from the console are not understandable. I couldn’t import an existing swagger spec, which by the way, is already available as a linked resource to the link given by @RudolfVonKrugstein.
Thus, one could assume that importing the example swagger spec, modifying it a bit and then exporting it will be ok, but I haven’t been able to make a stage for it so far, I still don’t know why, but I tend to believe that the swagger specification is still important.
My second and current approach, trying to make use of the serverless framework, is defining the resources in the
serverless.yaml of the given service, similarly to this example here. To be very honest, I am still not happy with this for 2 main reasons:
- It’s not using the swagger spec, making it too specific for the AWS infrastructure, which is not so interoperable.
- I haven’t been able to use
serverless-offline plugin so far. This would have been a good option to work with the API locally before it’s created on the AWS as a result of a Cloud Formation template generated by the serverless framework.
I’m still on my journey of figuring whether a good Cloud Formation template is better than a good swagger specification when it comes to integrating the serverless framework with the API Gateway. The variables feature in
serverless.yaml config has been really flexible so far to take values from all sorts of places, so I hope that maybe when the Cloud Formation format is good, it will be feasible to reference a swagger spec somehow in the
serverless.yaml file, so that both CF and swagger work well together.
At any case, the serverless provides mostly the deployment part of the task, not so much the local emulation of the AWS. For example, imagine being able to work only with
serverless-offline as a tool to both define, but also test the features locally and having the same definition again used as CF after serverless deployment.