Swagger and Serverless in parallel - bad idea?

If I like to keep my API definition in Swagger (mainly for the client code generation, and the docs), what are my options to still use Serverless in parallel?

There is this plugin but it is “not ready for use yet”.

I’m new to Swagger, but it seems like the de-facto standard for API specs - how do others tackle specs, documentation, code generation, etc. when they use serverless?

BTW, thanks for a great framework!


Seems like a popular idea, but I haven’t had a chance to do it myself.

This blog post details using Swagger JSON in CloudFormation, which means it will be possible to do it in Serverless.

You might have to take advantage of the fact that Serverless merges the contents of the resources section with the generated CFN template. Knowing that you could override the generated body field to inject your Swagger definition.
I’m not sure of any caveats or gotchas, but you’d have be familiar with the generated names of resource (e.g. functions, etc) to use in your Swagger.

If you do get it working, please share!

1 Like
  1. I am interested in a solution to that, as well.
  2. Is this something serverless should implement “natively” (referencing a swagger file)? This would solve a couple of other issues for me like binary media types.

While I think Swagger is cool, it seems like another case of API GW doing things differently/having multiple ways to do things (e.g. stages). It just doesn’t seem to play well with the other AWS services, but we obviously have no choice but use it…

My gut feel is that it’s still a bit early to integrate this kind of thing in to the Serverless core - it’s still relatively new and people are still working out the best way to use and integrate it. I think the use-cases need to be better understood.

If anyone out there has good, real-world examples (or detailed plans) where they’re using it and it’s working for them, it would be great to see.

1 Like

I would test to agree with what you’re saying. That does leave us with the question of how best to document APIs that we are deploying with Serverless. Are there any good tools or plugins out there? Ideally we’re looking for something that would allow the documentation to be embedded in the Serverless configuration and/or the lambda functions.