From 08a42961da26adc453d83b0c689e4d268ba3994d Mon Sep 17 00:00:00 2001
From: Sultan Iman <sultan.imanhodjaev@gmail.com>
Date: Thu, 1 Nov 2018 22:25:37 +0100
Subject: [PATCH] docs: document how custom error formatting works

---
 docs/custom-errors.rst | 51 ++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst         |  2 +-
 2 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100644 docs/custom-errors.rst

diff --git a/docs/custom-errors.rst b/docs/custom-errors.rst
new file mode 100644
index 0000000..f485d60
--- /dev/null
+++ b/docs/custom-errors.rst
@@ -0,0 +1,51 @@
+Custom errors
+=============
+
+Default GraphQL error format similar to the following snippet
+
+.. code: json
+
+    {
+      "errors": [
+        {
+          "message": "Variable \"$myAwesomeField\" of required type \"String!\" was not provided.",
+          "locations": [
+            {
+              "line": 1,
+              "column": 13
+            }
+          ]
+        }
+      ]
+    }
+
+And there is a way customise it by swapping default ``GraphQLView`` with your own
+and then override ``format_error`` method
+
+.. code: python
+    class MyGraphQLView(GraphQLView):
+        @staticmethod
+        def format_error(error) -> Dict[str, Any]:
+            if isinstance(error, GraphQLError):
+                return format_error(error)
+
+            return GraphQLView.format_error(error)
+
+
+Here is custom formatting function
+
+.. code: python
+  def format_error(error: GraphQLError) -> Dict[str, Any]:
+      """Extract field from ``error`` and return formatted error
+      :param error: GraphQLError
+      :return: mapping of fieldName -> error message
+      """
+      formatted_error = {
+          n.variable.name.value: str(error)
+          for n in error.nodes
+      }
+
+      if error.path:
+          formatted_error["path"] = error.path
+
+      return formatted_error
diff --git a/docs/index.rst b/docs/index.rst
index 7c64ae7..061cb90 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,4 +13,4 @@ Contents:
    debug
    rest-framework
    form-mutations
-   introspection
+   custom-errors