title: How to create API methods using rails & swagger docs for nested resources
body: <p>I have a rails application, using active record serializers to respond_to json or html. I'm using this to create a public API. I'm using devise simple http for basic authentication.</p>
  
  <p>I'm using Swagger docs, via the following gems. </p>
  
  <p><code>
  gem 'swagger-docs' #for creating the swagger json format
  gem 'swagger-ui_rails' #for generating the swanky active docs UI
  </code></p>
  
  <p>I have been able to create the json successfully for my main top level resources, via the controllers. For example, in "products_controller.rb":</p>
  
  <pre><code>swagger_controller :products, "Product Management"
  
    swagger_api :index do
      summary "Fetches all Products"
      param :query, :page, :integer, :optional, "Page number"
      response :unauthorized
      response :success
    end
  </code></pre>
  
  <p>The problem is how to setup for nested resources.</p>
  
  <p>So, in my architecture, Products has_many Slots / Slots belong to Product. So, in my "slots_controller.rb", I have it setup in the same fashion:</p>
  
  <pre><code>swagger_controller :slots, "Slot Management"
  
    swagger_api :index do
      summary "Fetches all Slots for a Product"
      param :query, :page, :integer, :optional, "Page number"
      param :form, :product_id, :integer, :required, "Product id"
      response :unauthorized
      response :success
    end
  </code></pre>
  
  <p>I think it was wishful thinking, that providing the param of <code>:product_id</code> along with the controller action working with the product id to find slots for the given product, then swagger may auto-magically interpret this as a nested resource. It seems not, and instead, my slots API method in Swagger is looking for:</p>
  
  <pre><code>/api/v1/slots.json
  </code></pre>
  
  <p>instead of </p>
  
  <pre><code>/api/v1/products/#{product.id}/slots
  </code></pre>
  
  <p>How do I setup my swagger_controller to generate the correct nested url structure for Slots?</p>