docs: Add documentation for field mappings

Signed-off-by: Tormod Haugland <tormod.haugland@gmail.com>

docs/guide/field-mappings.rst

@@ -0,0 +1,122 @@
+.. _field_name_mappings:
+
+================================
+Field name mappings
+================================
+
+*This feature is currently not implemented for DjangoFilterUpdateMutation.*
+
+Regular field name mappings
+------------------------------------
+
+Field mappings are used to rename model fields when creating the associated input fields. For instance,
+say you have a model with a field called "full_name", but you want it to be named "name" in the mutation
+input variables. You can achieve this by adding a `field name mapping` to the mutation:
+
+.. code:: python
+
+    class UpdateUserMutation(DjangoUpdateMutation):
+        class Meta:
+            model = User
+            field_name_mappings = {"full_name": "name"}
+
+The field name mappings are also available for `many_to_many_extras`, `many_to_one_extras` and `foreign_key_extras` arguments.
+
+.. code:: python
+
+    class UpdateUserMutation(DjangoUpdateMutation):
+        class Meta:
+            model = User
+            many_to_one_extras = {
+                "cats": {
+                    "exact": {
+                        "type": "auto",
+                        "field_name_mappings": {"full_name": "name"}
+                    }
+                }
+            }
+
+This will rename the field "full_name" to "name" in the input type for the "cats" relationship.
+
+
+Foreign key id suffixes and many to many id suffixes
+------------------------------------------------------
+Two mappings have specialized handling, namely adding an "_id" suffix to foreign key fields, and and "_ids" suffix
+to many to many fields. They can be enabled by adding the following flags respectively:
+
+* `use_id_suffixes_for_fk`
+* `use_id_suffixes_for_m2m`
+
+Having "id"/"ids" suffixes in APIs is a common pattern, and hence we have a special flag to enable this behaviour.
+
+You can also enable these fields globally by adding the following to your settings:
+
+.. code:: python
+
+    GRAPHENE_DJANGO_CUD_USE_ID_SUFFIXES_FOR_FK = True # / False, defaults to False
+    GRAPHENE_DJANGO_CUD_USE_ID_SUFFIXES_FOR_M2M = True # / False, defaults to False
+
+
+Example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: python
+
+    class User(models.Model):
+        name = models.CharField(max_length=255)
+        address = models.TextField()
+
+
+    class Dog(models.Model):
+        owner = models.ForeignKey(User, on_delete=models.CASCADE, related_name="dogs")
+        name = models.TextField()
+
+
+    class Cat(models.Model):
+        owner = models.ForeignKey(User, on_delete=models.CASCADE, related_name="cats")
+        name = models.TextField()
+        enemies = models.ManyToManyField(Dog, blank=True, related_name="enemies")
+
+    class UserNode(DjangoObjectType):
+        class Meta:
+            model = User
+            interfaces = (Node,)
+
+    class CatNode(DjangoObjectType):
+        class Meta:
+            model = Cat
+            interfaces = (Node,)
+
+    class DogNode(DjangoObjectType):
+        class Meta:
+            model = Dog
+            interfaces = (Node,)
+            use_id_suffixes_for_m2m = True
+
+
+    class CreateDogMutation(DjangoCreateMutation):
+        class Meta:
+            model = Dog
+            interfaces = (Node,)
+            use_id_suffixes_for_m2m = True
+            use_id_suffixes_for_fk = True
+
+
+    class Mutation(graphene.ObjectType):
+        create_dog = CreateDogMutation.Field()
+
+
+.. code::
+
+    mutation{
+        createDog(input: {name: "Sparky", ownerId: "1", enemiesIds: ["2", "3"]}){
+            dog{
+                id
+                name
+                owner{
+                    id
+                    name
+                }
+            }
+        }
+    }

docs/index.rst

@@ -22,6 +22,7 @@ helper classes designed to fast-track creation of create, update and delete muta
    guide/other-hooks
    guide/naming
    guide/field-types
+   guide/field-mappings
    guide/custom-fields
    guide/reusing-types
    guide/limitations