title: Swagger documentation tools for a Rails API application
body: <p>I googled a little bit to find a proper and easy to implement way to generate <a href="https://swagger.io/" rel="noreferrer">Swagger</a> documentation for an existing Rails API app. To be short, there are 2 ways of implementation: either via controllers, models or via Rspec controller/request specs. The list is not too long and the choice is not so easy to make:</p>
  
  <ol>
  <li><a href="https://github.com/richhollis/swagger-docs" rel="noreferrer">swagger-docs</a> gem, - the oldest one. Pros: implementation is to be
  done in  controllers. Cons: does not support Swagger <strong>V2</strong> version
  and limited to <strong>1.2</strong> only.</li>
  <li><a href="https://github.com/fotinakis/swagger-blocks" rel="noreferrer">swagger-blocks</a> gem, - improved version of swagger-docs, supports Swagger V2 version, implementation is to be done in controllers, models. But I couldn't make it work, <a href="https://editor.swagger.io/" rel="noreferrer">Swagger Editor</a> could not parse the generated json file.</li>
  <li><a href="https://github.com/domaindrivendev/rswag" rel="noreferrer">rswag</a> gem:  extends rspec-rails "request specs" with a Swagger-based DSL. Personally, I found it really difficult to implement in an existing Rails app for 2 reasons:
  
  <ul>
  <li>you will have to modify existing request specs</li>
  <li>request specs look really weird and the syntax is not <em>RSpec</em>-ish.</li>
  </ul></li>
  <li><a href="https://github.com/drewish/rspec-rails-swagger" rel="noreferrer">rspec-rails-swagger</a> gem: implementation via request specs. The same cons as above.</li>
  </ol>
  
  <p>Does anybody know other gems to generate Swagger documentation for an existing Rails API app ? Any suggestions are welcome ! Thank you.</p>