Documents per-model serialization changes.

CHANGES

@@ -28,6 +28,9 @@ Not yet released.
 - #449: roll back the session on any SQLAlchemy error, not just a few.
 - #436, #453: use ``__table__.name`` instead of ``__tablename__`` to infer the
   collection name for the SQLAlchemy model.
+- #440, #475: uses the serialization function provided at the time of invoking
+  :meth:`APIManager.create_api` to serialize each resource correctly, depending
+  on its type.
 - #474: include license files in built wheel for distribution.
 
 Older versions

docs/api.rst

@@ -18,6 +18,8 @@ in Flask-Restless.
 
 .. autofunction:: model_for(collection_name, _apimanager=None)
 
+.. autofunction:: serializer_for(model, _apimanager=None)
+
 .. autofunction:: url_for(model, instid=None, relationname=None, relationinstid=None, _apimanager=None, **kw)
 
 .. autoclass:: ProcessingException

docs/customizing.rst

@@ -195,11 +195,34 @@ follows::
 
 For a complete version of this example, see the
 :file:`examples/server_configurations/custom_serialization.py` module in the
-source distribution, or `view it online`_
+source distribution, or `view it online`_.
 
 .. _Marshmallow: https://marshmallow.readthedocs.org
 .. _view it online: https://github.com/jfinkels/flask-restless/tree/master/examples/server_configurations/custom_serialization.py
 
+Per-model serialization
+-----------------------
+
+The correct serialization function will be used for each type of SQLAlchemy
+model for which you invoke :meth:`APIManager.create_api`. For example, if you
+create two APIs, one for ``Person`` objects and one for ``Article`` objects, ::
+
+    manager.create_api(Person, serializer=person_serializer)
+    manager.create_api(Article, serializer=article_serializer)
+
+and then make a request like
+
+.. sourcecode:: http
+
+   GET /api/article/1?include=author HTTP/1.1
+   Host: example.com
+   Accept: application/vnd.api+json
+
+then Flask-Restless will use the ``article_serializer`` function to serialize
+the primary data (that is, the top-level ``data`` element in the response
+document) and the ``person_serializer`` to serialize the included ``Person``
+resource.
+
 .. _validation:
 
 Capturing validation errors