Generate and publish Ruby based REST APIs documentation

Question

What are cool kids using nowadays to easily parse/generate/publish REST APIs? I took a look on Swagger and It looks nice but from my point of view it doesn't fit ok with Ruby. Maybe I'm just wrong and I'm missing something, help would be appreciated.

Answer 1

Sounds like you don't have an API yet? If that's the case, this is the approach that I recommend.

• Create an interface for the API by using the swagger-specification. You can do this without using a server, see here.

• Verify the interface by using swagger-ui. This allows you to see all the endpoints that you've defined (still, no coding, except for the json files!)

• Once you have an interface you want, use swagger-codegen to build a stubbed-out version of your server. There are currently templates for nodejs and scalatra with more on the way. Making a new server generator is simply a matter of creating/modifying some mustache templates.

• You can also generate your client with swagger-codegen.

The beauty of this is that you can do interface-driven development of your API. Build the interfaces and fill in the blanks. The plumbing is done for you.