GraphqlRails

Rails style structure for GraphQL API.

Installation

Add this line to your application's Gemfile:

gem 'graphql_rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install graphql_rails

Getting started

Execute:

$ bundle exec rails g graphql_rails:install

This will generate code which will let you start your graphql faster

Usage

Define GraphQL schema as RoR routes

# config/graphql/routes.rb
GraphqlRails::Router.draw do
  # will create createUser, updateUser, destroyUser mutations and user, users queries.
  # expects that UsersController class exist
  resources :users

  # if you want custom queries or mutation
  query 'searchLogs', to: 'logs#search' # redirects request to LogsController
  mutation 'changeUserPassword', to: 'users#change_password'
end

Define your Graphql model

# app/models/user.rb
class User # works with any class including ActiveRecord
  include GraphqlRails::Model

  graphql do |c|
    # most common attributes, like :id, :name, :title has default type, so you don't have to specify it (but you can!)
    c.attribute :id

    c.attribute :email, type: :string
    c.attribute :surname, type: :string
  end
end

Define controller

# app/controllers/graphql/users_controller.rb
class Graphql::UsersController < GraphqlApplicationController
  # graphql requires to describe which attributes controller action accepts and which returns
  action(:change_user_password)
    .permit(:password!, :id!) # Bang (!) indicates that attribute is required
    .returns('User!')

  def change_user_password
    user = User.find(params[:id])
    user.update!(password: params[:password])

    # returned value needs to have all methods defined in model `graphql do` part
    user # or SomeDecorator.new(user)
  end

  action(:search)
    .permit(search_fields!: SearchFieldsInput) # you can specify your own input fields
    .returns('[User!]!')
  def search
  end
end

Routes

GraphqlRails::Router.draw do
  # generates `friend`, `createFriend`, `updateFriend`, `destroyFriend`, `friends` routes
  resources :friends
  resources :shops, only: [:show, :index] # generates `shop` and `shops` routes only
  resources :orders, except: :update # generates all routes except `updateOrder`

  resources :users do
    # generates `findUser` query
    query :find, on: :member

    # generates `searchUsers` query
    query :search, on: :collection
  end

  # you can use namespaced controllers too:
  scope module: 'admin' do
    # `updateTranslations` route will be handled by `Admin::TranslationsController`
    mutation :updateTranslations, to: 'translations#update'

    # all :groups routes will be handled by `Admin::GroupsController`
    resources :groups
  end
end

Testing your GraphqlRails::Controller in RSpec

Setup

Add those lines in your spec/spec_helper.rb file

# spec/spec_helper.rb
require 'graphql_rails/rspec_controller_helpers'

RSpec.configure do |config|
  config.include(GraphqlRails::RSpecControllerHelpers, type: :graphql_controller)
  # ... your other configuration ...
end

Helper methods

There are 3 helper methods:

mutation(:your_controller_action_name, params: {}, context: {}). params and context are optional
query(:your_controller_action_name, params: {}, context: {}). params and context are optional
response. Response is set only after you call mutation or query

Test examples

class MyGraphqlController
  action(:create_user).permit(:full_name, :email).returns(User)
  action(:index).returns('String')

  def index
    "Called from index: #{params[:message]}"
  end

  def create_user
    User.create!(params)
  end
end

RSpec.describe MyGraphqlController, type: :graphql_controller do
  describe '#index' do
    it 'is successful' do
      query(:index)
      expect(response).to be_successful
    end

    it 'returns correct message' do
      query(:index, params: { message: 'Hello world!' })
      expect(response.result).to eq "Called from index: Hello world!"
    end
  end

  describe '#create_user' do
    context 'when bad email is given' do
      it 'fails' do
        mutation(:create_user, params { email: 'bad' })
        expect(response).to be_failure
      end

      it 'contains errors' do
        mutation(:create_user, params { email: 'bad' })
        expect(response.errors).not_to be_empty
      end
    end
  end
end

Integrating GraphqlRails with other tools

In order to make GraphqlRails work with tools such as lograge or sentry, you need to enable them. In Ruby on Rails, you can add initializer:

# config/initializers/graphql_rails.rb
GraphqlRails::Integrations.enable(:lograge, :sentry)

At the moment, GraphqlRails supports following integrations:

lograge
sentry

If you need to build something custom, check logging_and_monitoring documentation for more details.

Detailed documentation

Check https://samesystem.github.io/graphql_rails for more details

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/samesystem/graphql_rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.