Examples of using Swagger (or Simplify to avoid needing them)

[johnc44]

Would it be possible to add some samples showing how to use Swagger? It's all quite unintuitive to me and the documentation currently isn't that helpful. I found a really old example that didn't help very much, so something that really shows how to use it.

In particular considering both inline swagger (in template.yml) and external in a swagger.yml file.

I did manage to get something working but it feels pretty unintuitive so I'm not sure it's the right way. (Or if it is, it feels like something that should be easier to do)

It seems I need to list every endpoint twice, once under the function's Events, and then again under the swagger document. And then the swagger bit needs an AWS extension to hook it back up to the lambda, but this needs a url being generated using string replacement etc.

Firstly, it would be really nice if SAM could just simplify this. If I need a Swagger spec that has all the information in it, why do I need to list the events a second time under Events in the function? And can the Swagger spec be simplified so I don't need to manipulate AWS ARNs by hand? (And this seems to be particularly problematic if I use an external Swagger file).

But in any case. I think one or two samples showing the SAM recommended way of setting up an API using Swagger help clear a lot of this up.

[keetonian]

@johnc44 have you tried letting SAM generate the swagger for you? If you don't have a DefinitionBody or a DefinitionUri, SAM will generate swagger on your Serverless::Api based on the Events that reference it.

[johnc44]

Thanks very much for the reply. I could have sworn I read that one or the other was required, but I've just tried it and it does seem to work. (And I checked the docs which also say that this is possible.)

I'll have to try it with path params too, but I presume that will work, in which case that's a better solution than what we have right now.

The only problem is that this looks quite limited - I can define enough for my lambda to work, but not enough to provide full documentation of my API. For example, what responses can be expected. (Unless I'm missing that too?)

I like the idea of having an external swagger document that I can version control independently of the template.yml but it does feel that at the moment it's a bit too hacky to be worthwhile.

[keetonian]

@johnc44 one or the other used to be necessary. It is possible that some part of the docs or examples still says that this is a requirement, if you find it let us know and we (or you, if you'd like to submit a PR) can change that.

I'm not very familiar with all the APIGW features, but for responses, will the upcoming GatewayResponses feature (#841) work for responses and documentation?

[johnc44]

Thanks very much for the reply. I think being able to define responses might well help. I had a very quick look at the PR and it seems like you define responses on the gateway not individual methods.

I think for each method I'd like to define what the request and response JSONs look like, as well perhaps as what status codes they might return. I am new to Swagger though, but believe this sort of thing can go in a Swagger doc. (I was hoping that SAM would be my way in to learn about Swagger.)

It might also be useful to be able to provide descriptions for each method.

Re the docs - they've either changed or I remembered it wrong as I can't find anywhere that says that the one of the 2 properties must be defined now.

[beck3905]

@keetonian @johnc44 I have been going back and forth on whether to defined my own swagger (inline) or to just let SAM do it for me. I've mostly settled on letting SAM do it for me, but there are definitely some limitations to this because it seems to be san all or nothing scenario. If I want to customize anything in my API (e.g defining method requests/models/validators and method responses) then I have to define my whole API in swagger. This becomes cumbersome for developers who need to modify an existing function or add a new function to the API as now they have to write a bunch of swagger and extensions. Our goal with using SAM is to make the development and deployment of API endpoints as trivial as possible so our developers can focus on the business logic in the lambdas.

I would be nice to add options to the API event source for AWS::Serverless::Function for models (request and response) and validators similar to how authorizers can be defined in there now without having to dive into swagger.

[keetonian]

@beck3905 adding support for models I think would make it easier to use the SAM-generated swagger. I opened a new issue (#895) with a proposal about how to add APIGW models to SAM.