Merge pull request #18 from driggl/12-improve-documentation

Improve documentation

Author: Sebastian Wilgosz

README.md

@@ -32,10 +32,10 @@ rescue_from ::StandardError, with: lambda { |e| handle_error(e) }
 ```
 
 From this point you'll have default html errors being serialized. JsonapiErrorsHandler offers 4 predefined errors:
-- JsonapiErrorsHandler::Errors::Invalid
-- JsonapiErrorsHandler::Errors::Forbidden
-- JsonapiErrorsHandler::Errors::NotFound
-- JsonapiErrorsHandler::Errors::Unauthorized
+- [JsonapiErrorsHandler::Errors::Invalid](https://github.com/driggl/jsonapi_errors_handler/blob/master/lib/jsonapi_errors_handler/errors/invalid.rb)
+- [JsonapiErrorsHandler::Errors::Forbidden](https://github.com/driggl/jsonapi_errors_handler/blob/master/lib/jsonapi_errors_handler/errors/forbidden.rb)
+- [JsonapiErrorsHandler::Errors::NotFound](https://github.com/driggl/jsonapi_errors_handler/blob/master/lib/jsonapi_errors_handler/errors/not_found.rb)
+- [JsonapiErrorsHandler::Errors::Unauthorized](https://github.com/driggl/jsonapi_errors_handler/blob/master/lib/jsonapi_errors_handler/errors/not_found.rb)
 
 If you rise any of errors above in any place of your application, client gets the nicely formatted error message instead of 500
 
@@ -52,6 +52,57 @@ ErrorsMapper.map_errors!({
 rescue_from ::StandardError, with: lambda { |e| handle_error(e) }
 ```
 
+###Custom error logging
+
+When you'll include the `jsonapi_errors_handler` to your controller, all errors will be handled and delivered to the client in the nice, formatted
+way.
+
+However, you'd probably like to have a way to log the risen error on your own to send notifications to developers that
+something unexpected happened.
+
+To do so, just implement the `log_error` method in your controller, that accepts the risen error as an argument.
+
+```
+  def log_error(error)
+    #do the fancy logging here
+  end
+```
+
+### Custom error responses.
+
+By default, we deliver hardcoded responses. You can check out the defined error classes for details
+
+- [JsonapiErrorsHandler::Errors::Invalid](https://github.com/driggl/jsonapi_errors_handler/blob/master/lib/jsonapi_errors_handler/errors/invalid.rb)
+- [JsonapiErrorsHandler::Errors::Forbidden](https://github.com/driggl/jsonapi_errors_handler/blob/master/lib/jsonapi_errors_handler/errors/forbidden.rb)
+- [JsonapiErrorsHandler::Errors::NotFound](https://github.com/driggl/jsonapi_errors_handler/blob/master/lib/jsonapi_errors_handler/errors/not_found.rb)
+- [JsonapiErrorsHandler::Errors::Unauthorized](https://github.com/driggl/jsonapi_errors_handler/blob/master/lib/jsonapi_errors_handler/errors/not_found.rb)
+
+If you want to have custom error responses being delivered, just create your own `Api::Errors` that inherits from `JsonapiErrorsHandler::StandardError`
+
+### Localization example
+
+If you want to localize your responses, just create a class:
+
+```
+  module Api::Errors
+    class Forbidden < ::JsonapiErrorsHandler::Errors::StandardError
+      def initialize(*)
+        super(
+          title: I18n.t('api.errors.forbidden.title'),
+          status: 403,
+          detail: I18n.t('api.errors.forbidden.detail'),
+          source: { pointer: '/request/headers/authorization' }
+        )
+      end
+    end
+  end
+```
+
+## Guides & tutorials
+
+- [Handling Exceptions in Rails Applications](https://driggl.com/blog/a/handling-exceptions-in-rails-applications) - Gem's concept explained in details
+- [JsonApi Errors Handler Guide](https://driggl.com/blog/a/json-api-errors-handler)
+
 ## 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.
@@ -65,6 +116,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/driggl
 **How to contribute:**
 
 1. Fork repository
+2. Install [Rubocop](https://github.com/rubocop-hq/rubocop) - make sure you run it before commiting changes
 2. Commit changes
     - Keep commits small and atomic
     - Start commit message from keywords (Add/Remove/Change/Refactor/Move/Rename/Upgrade/Downgrade)