task: improve docs for custom persistence options

Author: alastairtree

README.md

@@ -14,6 +14,7 @@ dotnet add package JsonApiDotNetCore.MongoDb
 ### Models
 
 ```cs
+// MongoDbIdentifiable is just a utility base class, could use  IIdentifiable<TId> instead
 public sealed class Book : MongoDbIdentifiable
 {
     [Attr]
@@ -63,14 +64,16 @@ public class Startup
     }
 }
 ```
+
 Note: If your API project uses only MongoDB (not in combination with EF Core), then instead of
 registering all MongoDB resources and repositories individually, you can use:
+
 ```cs
 public class Startup
 {
     public IServiceProvider ConfigureServices(IServiceCollection services)
     {
-	// ...
+        // ...
 
         services.AddJsonApi(facade => facade.AddCurrentAssembly());
         services.AddJsonApiMongoDb();
@@ -85,6 +88,60 @@ public class Startup
 }
 ```
 
+### Customise MongoDB persistence options and _id generation
+
+In addition to `MongoDbIdentifiable` your resource classes are free to use any of the MongoDB driver persistence options or inherit from their own base class.
+
+For example, you could change the example above so that the `Book` resource has string IDs rather than object ids in the DB, but still have them generated server side:
+
+```cs
+public class Book : IIdentifiable<string>
+{
+    // If Id=null generate a random string ID using the MongoDB driver
+    [BsonId(IdGenerator = typeof(StringObjectIdGenerator))]
+    [Attr]
+    public virtual string Id { get; set; }
+
+    // override the attribute name in the db
+    [BsonElement("bookName")]
+    [Attr]
+    public string Name { get; set; }
+
+    // all json:api resources need this
+    [BsonIgnore]
+    public string StringId { get => Id; set => Id = value; }
+}
+```
+
+Resources just need to inherit from the base `IIdentifiable<string>` interface from JsonApiDotNetCore (or the provided default `MongoDbIdentifiable`) and then just use any of usual [MongoDB Driver mapping code](https://mongodb.github.io/mongo-csharp-driver/2.12/reference/bson/mapping/).
+
+You could also achieve the exact same result using MongoDB `BsonClassMap` [rather than attributes](https://mongodb.github.io/mongo-csharp-driver/2.11/reference/bson/mapping/) so your `Book` does not need any MongoDB specific code like below.
+
+```cs
+    // in startup
+    BsonClassMap.RegisterClassMap<Book>(cm =>
+    {
+        cm.AutoMap();
+        cm.MapIdProperty(x => x.Id).SetIdGenerator(StringObjectIdGenerator.Instance);
+        cm.UnmapMember(x=>x.StringId);
+    });
+```
+
+Using `StringObjectIdGenerator` above could then be combined with `AllowClientGeneratedIds` JsonApi setting in `Startup.ConfigureServices` so that IDs can be generated on the client, and will be auto-assigned server side if not provided providing a flexible string based id for the `Book` resource:
+
+```cs
+    services.AddJsonApi(options => {
+        // Allow us to POST books with already assigned IDs!
+        options.AllowClientGeneratedIds = true;
+    }, resources: builder =>
+    {
+        builder.Add<Book, string>();
+    });
+    services.AddJsonApiMongoDb();
+
+    services.AddResourceRepository<MongoDbRepository<Book, string>>();
+```
+
 ## Development
 
 Restore all NuGet packages with: