django-rest-marshmallow

Marshmallow模式 for Django REST framework.

概述

django-rest-marshmallow通过使用python marshmallow库，提供了一个内置序列化器的替代实现，同时公开与REST framework的Serializer类相同的API。

要求

• Python (2.7, 3.5+)
• Django REST framework (3.8+)
• Marshmallow (2.15+ and 3.0.0b18+)

安装

使用pip安装...

$ pip install django-rest-marshmallow

使用方法

像使用marshmallow一样定义您的模式，但导入来自rest_marshmallow的Schema类。

from rest_marshmallow import Schema, fields

class CustomerSchema(Schema):
    name = fields.String()
    email = fields.Email()
    created_at = fields.DateTime()

Schema类具有与Django REST framework序列化器相同的接口，因此您可以在通用视图中使用它...

class CustomerListView(generics.ListAPIView):
    queryset = Customer.objects.all()
    serializer_class = CustomerSchema

或直接使用序列化器API，用于序列化...

serializer = CustomerSchema(queryset, many=True)
return Response(serializer.data)

或用于验证...

serializer = CustomerSchema(data=request.data)
serializer.is_valid(raise_exception=True)
serializer.validated_data

实例创建和更新

如果您想支持 serializer.save()，则需要显式定义 .create() 和/或 .update() 方法。

class CustomerSchema(Schema):
    name = fields.String()
    email = fields.Email()
    created_at = fields.DateTime()

    def create(self, validated_data):
        return Customer.objects.create(**validated_data)

    def update(self, instance, validated_data):
        for key, value in validated_data.items():
            setattr(instance, key, value)
        instance.save()
        return instance

现在您可以从视图代码中使用 .save()...

serializer = CustomerSchema(data=request.data)
serializer.is_valid(raise_exception=True)
serializer.save()
return Response(serializer.data, status=status.HTTP_201_CREATED)

或者使用与创建或更新实例的通用视图一起使用的模式...

class CustomerListView(generics.ListCreateAPIView):
    queryset = Customer.objects.all()
    serializer_class = CustomerSchema

请注意，您应该始终使用 create() 和 update() 方法而不是重写 marshmallow 的 make_object() 方法。

嵌套表示

对于嵌套表示，通常使用 marshmallow 的标准 Nested 字段。

from rest_marshmallow import fields, Schema

class ArtistSchema(Schema):
    name = fields.String()

class AlbumSchema(Schema):
    title = fields.String()
    release_date = fields.Date()
    artist = fields.Nested(ArtistSchema)

排除字段

Marshmallow 的 only 和 exclude 参数也作为序列化器的参数有效。

serializer = CustomerSchema(queryset, many=True, only=('name', 'email'))
return Response(serializer.data)

测试

安装测试需求。

$ pip install -r requirements.txt

使用 runtests 运行。

$ ./runtests.py

您还可以使用出色的 tox 测试工具运行针对所有支持的 Python 和 Django 版本的测试。全局安装 tox，然后简单地运行

$ tox

文档

要构建文档，您需要安装 mkdocs。

$ pip install mkdocs

预览文档

$ mkdocs serve
Running at: http://127.0.0.1:8000/

构建文档

$ mkdocs build