# Resource-specific documentation
# include into controller
# 
module UsersDoc
  extend BaseDoc
  resource :users

  resource_description do
    formats [:json]
    api_versions 'public'
  end

  doc_for :index do
    api :GET, '/users', 'List users'
    param :role, String, 'Filter users by role'
  end

  doc_for :show do
    api! 'Show user'
    description 'Returns user with provided id'
    param :id, String, 'Id of user you want to fetch'
  end

  doc_for :create do
    api! 'Create user'
    description 'Create user with specifed user params'
    param :user, Hash, desc: 'User information' do
      param :full_name, String, desc: 'Full name of the user you want to create'
      param :age, Fixnum, desc: 'Age of the user you want to create'
    end
  end
end