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

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.