We don't use cloudformation because honestly, it sucks. It's hard limits are a pain in the ass to get around (with 150 lambda functions, we need hundreds of resources, so that means nested stacks, which just suck) and it managing the api gateway just doesn't do what we want.
We have a custom script to deploy our own API Gateway using the AWS SDK and we generate a swagger file from simple json config files.
For the API Gateway issues, so far, we have a few things that are something we have to watch out for.
- All lambda endpoints through APIG are lambda proxy type. This means we can have a framework handle standard request / response stuff. The downside is that we can't support binary endpoints easily because they haven't fixed that issue yet.
- HTTP proxy pass through endpoints have to be added to the swagger somehow before we deploy. This is a little annoying, but not a huge issue
- Merge vs Override for deployments. We merge in beta, and override in other environments. This allows us to keep endpoints exactly as they are, but allow flexible testing in beta
1 APIG for 1 micro service isn't great IMO at scale since we run all our endpoints under on domain and mapping all of them would be a pain.