Dox.txt

 1 - install-
    group :test do
      gem 'dox', require: false
    end
     
 ** make sure you have data in your test database.

-----------------------------------------------
 2-  bundle
-----------------------------------------------
 3- require 'dox' in rails_helper
------------------------------------------------
 4- configure rails_helper with this - 
      RSpec.configure do |config|
        config.after(:each, :dox) do |example|
          example.metadata[:request] = request
          example.metadata[:response] = response
        end
      end
-------------------------------------------------
 5-Set these mandatory options in the rails_helper:

    Dox.configure do |config|
     config.header_file_path = Rails.root.join('spec/docs/v1/descriptions/header.md')
     config.desc_folder_path = Rails.root.join('spec/docs/v1/descriptions')
     config.headers_whitelist = ['Accept', 'X-Auth-Token']
   end
   
 IN MY CASE - Dox.configure do |config|
  config.header_file_path = Rails.root.join('spec/apis_doc/descriptions/header.md')
  config.desc_folder_path = Rails.root.join('spec/apis_doc/descriptions')
  config.headers_whitelist = ['Accept']
end


-------------------------------------------------------------------------------
   6- Define a descriptor module for a resource using Dox DSL:

       module Docs
  module V1
    module Bids
      extend Dox::DSL::Syntax

      # define common resource data for each action
      document :api do
        resource 'Bids' do
          endpoint '/bids'
          group 'Bids'
        end
      end

      # define data for specific action
      document :index do
        action 'Get bids'
      end
    end
  end
end

NOTE - IN MY CASE - example - spec/apis_doc/customers.rb 

   module ApisDoc
  module Customers
    extend Dox::DSL::Syntax
      document :apis do
        resource 'Customers' do
          endpoint '/customers'
          group 'Customers'
        end
        group 'Customers' do
          desc 'Customers group'
        end
      end
      document :customer_list do
        action 'Get customers'
      end
  end
end
--------------------------------------------------------------------------------------------------

7- You can define the descriptors for example in specs/docs folder, just make sure you load them in the rails_helper.rb:
Dir[Rails.root.join('spec/docs/**/*.rb')].each { |f| require f }

NOTE - IN MY CASE - 
Dir[Rails.root.join('spec/apis_doc/**/*.rb')].each { |f| require f }
-----------------------------------------------------------------------------------------------------

8- Include the descriptor modules in a controller and tag the specs you want to document with dox:

   describe Api::V1::BidsController, type: :controller do
  # include resource module
  include Docs::V1::Bids::Api

  describe 'GET #index' do
    # include action module
    include Docs::V1::Bids::Index

    it 'returns a list of bids', :dox do
      get :index
      expect(response).to have_http_status(:ok)
    end
  end
end

NOTE - IN MY CASE - customers_controller_spec.rb
  
  require 'rails_helper'
  require "spec_helper"

RSpec.describe Apis::CustomersController, api: true, type: :controller do
  include ApisDoc::Customers::Apis
  describe "GET #CustomerList" do
    include ApisDoc::Customers::CustomerList
      context 'customer list' do
        before(:each) do
          request.headers["format"] = "json"
          request.headers["Content-Type"] = "application/json"
          request.headers["REQUEST_PATH"] = "/apis/customers/customer_list.json"
          request.headers["REQUEST_URI"] = "/apis/customers/customer_list.json"
          request.headers["PATH_INFO"] = "/apis/customers/customer_list.json"
          request.headers["HTTP_USER_ID"] = "3"
          request.headers["HTTP_ACCESS_TOKEN"] = "3a29ddd839088b4ac5e1ff7454b87eea"
        end
        it 'returns a list of customers', :dox do
          get :customer_list
          expect(response).to have_http_status(:ok)
        end
      end
  end
end
----------------------------------------------------------------------------------------------------
 9- Use the following commands to create .md and .index files - 
 bundle exec rspec spec/controllers/api/v1 -f Dox::Formatter --order defined --tag dox --out docs.md
bundle exec rspec spec/controllers/api/v1 -f Dox::Formatter --order defined --tag dox --out docs.html

NOTE - IN MY CASE - bundle exec rspec spec/controllers/apis -f Dox::Formatter --order defined --tag dox --out docs.md
bundle exec rspec spec/controllers/apis -f Dox::Formatter --order defined --tag dox --out docs.html


=================================================================================================

NOTE - In my case files are created in the root directory of an application.	

-------------------------------------------------------------------------------------------------
Also -> create a empty file in-  spec 
                                    -> apis_doc
                                           -> descriptions  
                                                    -> header.md