Merge pull request #84 from graphql-devise/improve-readme-file

Improve readme file

.gitignore

@@ -7,6 +7,8 @@
 /spec/reports/
 /tmp/
 
+README.md.*
+
 # rspec failure tracking
 .rspec_status
 /spec/dummy/log/

README.md

@@ -5,6 +5,46 @@
 
 GraphQL interface on top of the [Devise Token Auth](https://github.com/lynndylanhurley/devise_token_auth) (DTA) gem.
 
+## Table of Contents
+
+<!--ts-->
+   * [GraphqlDevise](#graphqldevise)
+      * [Table of Contents](#table-of-contents)
+      * [Introduction](#introduction)
+      * [Installation](#installation)
+      * [Usage](#usage)
+         * [Mounting Routes manually](#mounting-routes-manually)
+            * [Available Operations](#available-operations)
+         * [Configuring Model](#configuring-model)
+         * [Customizing Email Templates](#customizing-email-templates)
+         * [I18n](#i18n)
+         * [Authenticating Controller Actions](#authenticating-controller-actions)
+         * [Making Requests](#making-requests)
+            * [Mutations](#mutations)
+            * [Queries](#queries)
+         * [More Configuration Options](#more-configuration-options)
+            * [Devise Token Auth Initializer](#devise-token-auth-initializer)
+            * [Devise Initializer](#devise-initializer)
+         * [Using Alongside Standard Devise](#using-alongside-standard-devise)
+      * [Future Work](#future-work)
+      * [Contributing](#contributing)
+      * [License](#license)
+
+<!-- Added by: mcelicalderon, at: Tue Apr 28 21:43:30 -05 2020 -->
+
+<!--te-->
+
+## Introduction
+This gem heavily relies on two gems, [Devise Token Auth](https://github.com/lynndylanhurley/devise_token_auth) (DTA)
+and [Devise](https://github.com/heartcombo/devise) which is a dependency of DTA.
+It provides a GraphQL interface on top of DTA which is designed to work with REST APIs. That's why
+things like token management, token expiration and everything up until using the actual GraphQL schema is
+still controlled by DTA. For that reason you will find that our generator runs these two gems generator and two
+initializer files are included. We'll provide more configuration details in the
+[configuration section](#more-configuration-options),
+but **we recommend you get familiar with [DTA and their docs](https://github.com/lynndylanhurley/devise_token_auth)
+in order to use this gem to its full potential**.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -17,13 +57,9 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
-
-    $ gem install graphql_devise
-
 Next, you need to run the generator:
 
-    $ rails generate graphql_devise:install
+    $ bundle exec rails generate graphql_devise:install
 
 Graphql Devise generator will execute `Devise` and `Devise Token Auth`
 generators for you. These will make the required changes for the gems to
@@ -36,7 +72,7 @@ The generator accepts 2 params: `user_class` and `mount_path`. The params
 will be used to mount the route in `config/routes.rb`. For instance the executing:
 
 ```bash
-$ rails g graphql_devise:install Admin api/auth
+$ bundle exec rails g graphql_devise:install Admin api/auth
 ```
 
 Will do the following:
@@ -51,9 +87,15 @@ Will do the following:
 `Admin` could be any model name you are going to be using for authentication,
 and `api/auth` could be any mount path you would like to use for auth.
 
+**Important:** Remember this gem mounts a completely separate GraphQL schema on a separate controller in the route
+provided by the `at` option in the `mount_graphql_devise_for` method in the `config/routes.rb` file. If no `at`
+option is provided, the route will be `/graphql_auth`. This has no effect on your own application schema.
+More on this in the next section.
+
+## Usage
 ### Mounting Routes manually
 Routes can be added using the initializer or manually.
-You can add a route like this:
+You can mount this gem's GraphQL auth schema in your routes file like this:
 
 ```ruby
 # config/routes.rb
@@ -157,7 +199,7 @@ end
 ```
 
 The install generator can do this for you if you specify the `user_class` option.
-See [Installation](#Installation) for details.
+See [Installation](#installation) for details.
 The generator will include a different module in your model, `DeviseTokenAuth::Concerns::User` which is also correct,
 we just made an alias on our namespace for consistency and possible extension.
 Generators have to be updated to generate our module.
@@ -214,10 +256,12 @@ Here is a list of the available mutations and queries assuming your mounted mode
 1. `userSignUp(email: String!, password: String!, passwordConfirmation: String!, confirmSuccessUrl: String): UserSignUpPayload`
 
    The parameter `confirmSuccessUrl` is optional unless you are using the `confirmable` plugin from Devise in your `resource`'s model. If you have `confirmable` set up, you will have to provide it unless you have `config.default_confirm_success_url` set in `config/initializers/devise_token_auth.rb`.
+1. `userSendResetPassword(email: String!, redirectUrl: String!): UserSendReserPasswordPayload`
 1. `userUpdatePassword(password: String!, passwordConfirmation: String!, currentPassword: String): UserUpdatePasswordPayload`
 
-    The parameter `currentPassword` is optional if you have `config.check_current_password_before_update` set to false (disabled by default) or the `resource` model supports the `recoverable` Devise plugin and the `resource`'s `allow_password_change` attribute is set to true.
-1. `userSendResetPassword(email: String!, redirectUrl: String!): UserSendReserPasswordPayload`
+    The parameter `currentPassword` is optional if you have `config.check_current_password_before_update` set to
+    false (disabled by default) on your generated `config/initializers/devise_token_aut.rb` or if the `resource`
+    model supports the `recoverable` Devise plugin and the `resource`'s `allow_password_change` attribute is set to true (this is done in the `userCheckPasswordToken` query when you click on the sent email's link).
 1. `userResendConfirmation(email: String!, redirectUrl: String!): UserResendConfirmationPayload`
 
     The `UserResendConfirmationPayload` will return the `authenticatable` resource that was sent the confirmation instructions but also has a `message: String!` that can be used to notify a user what to do after the instructions were sent to them
@@ -232,16 +276,52 @@ requests using the `GET` method on the Rails side, but looks like there might be
 on the [Apollo Client](https://www.apollographql.com/docs/apollo-server/v1/requests/#get-requests).
 
 We will continue to build better docs for the gem after this first release, but in the mean time
-you can use [our specs](https://github.com/graphql-devise/graphql_devise/tree/b5985036e01ea064e43e457b4f0c8516f172471c/spec/requests) to better understand how to use the gem.
-Also, the [dummy app](https://github.com/graphql-devise/graphql_devise/tree/b5985036e01ea064e43e457b4f0c8516f172471c/spec/dummy) used in our specs will give you
+you can use [our specs](spec/requests) to better understand how to use the gem.
+Also, the [dummy app](spec/dummy) used in our specs will give you
 a clear idea on how to configure the gem on your Rails application.
 
+### More Configuration Options
+As mentioned in the introduction there are many configurations that will change how this gem behaves. You can change
+this values on the initializer files generated by the installer.
+
+#### Devise Token Auth Initializer
+The generated initializer file `config/initializers/devise_token_auth.rb` has all the available options documented
+as comments. You can also use
+**[DTA's docs](https://devise-token-auth.gitbook.io/devise-token-auth/config/initialization)** as a reference.
+In this section the most important configurations will be highlighted.
+
+- **change_headers_on_each_request:** This configurations defaults to `true`. This means that tokens will change on
+  each request you make, and the new values will be returned in the headers. So your client needs to handle this.
+  Setting this to `false` will allow you to store the credentials for as long as the token life_span permits. And
+  you can send the same credentials in each request.
+- **batch_request_buffer_throttle:** When change_headers_on_each_request is set to true, you might still want your
+  credentials to be valid more than once as you might send parallel request. The duration you set here will
+  determine how long the same credentials work after the first request is received.
+- **token_lifespan:** This configuration takes a duration and you can set it to a value like
+  `1.month`, `2.weeks`, `1.hour`, etc.
+
+**Note:** Remember this gem adds a layer on top of DTA, so some configurations might not apply.
+
+#### Devise Initializer
+The generated initializer file `config/initializers/devise_token_auth.rb` has all the available options documented
+as comments. You can also use
+**[Devise's docs](https://github.com/heartcombo/devise)** as a reference.
+In this section the most important configurations will be highlighted.
+
+- **password_length:** You can change this value to validate password length on sign up and password update
+  (must enable the validatable module).
+- **mailer_sender:** Set it to a string with the sender's email address like `'support@example.com'`.
+- **case_insensitive_keys:** Setting a value like `[:email]` will make email field case insensitive on login, sign up, etc.
+- **email_regexp:** You can customize the regex that will validate the format of email addresses (must enable the validatable module).
+
+**Note:** Remember this gem adds a layer on top of Devise, so some configurations might not apply.
+
 ### Using Alongside Standard Devise
 The DeviseTokenAuth gem allows experimental use of the standard Devise gem to be configured at the same time, for more
 information you can check [this answer here](https://github.com/lynndylanhurley/devise_token_auth/blob/2a32f18ccce15638a74e72f6cfde5cf15a808d3f/docs/faq.md#can-i-use-this-gem-alongside-standard-devise).
 
-This gem supports the same and should be easier to handle email templates due to the fact we don't override standard Devise
-templates.
+This gem supports the same and should be easier to handle email templates due to the fact we don't override
+standard Devise templates.
 
 ## Future Work
 We will continue to improve the gem and add better docs.