Django restful framework生成API文档过程详解

我来为您讲述一下“Django restful framework生成API文档过程详解”的完整攻略。

1. 安装Django Rest Framework

在开始前，首先需要安装Django Rest Framework。可以在终端中运行以下命令安装：

pip install djangorestframework

2. 添加Django Rest Framework至Django工程

在Django工程的settings.py文件中添加以下内容：

INSTALLED_APPS = [
    ...
    'rest_framework',
]

这样就完成了Django Rest Framework的添加。

3. 配置文档生成器

Django Rest Framework提供了多个文档生成器，其中最为常用的是coreapi。在安装了Django Rest Framework之后，可以通过以下命令安装coreapi：

pip install coreapi

在settings.py文件中，添加以下配置：

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

这里配置了Django Rest Framework使用自动文档生成器AutoSchema。

4. 编写文档注释

在编写API接口时，需要在Django视图函数中写上对应的文档注释。以下是一个示例：

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.schemas import AutoSchema

class HelloView(APIView):
    """
    简要描述视图函数的功能。

    更具体的功能描述。
    """
    schema = AutoSchema(
        manual_fields=[
            # 添加手动设置的字段
        ]
    )

    def get(self, request):
        """
        列出 GET 请求可用的已经注册的 echo 接口。

        下面是一些关于这个 API 接口描述的 **更加详细的信息**。

        记得把请求 GET /echo/?format=api 输出的结果也填写到样例里面。

        """
        return Response({'message': 'Hello, World!'})

如上所示，可以在类上方使用三引号写出简要描述和更具体的描述，而在每个方法上方用三引号写出该方法的详细描述。

此外，可以通过在schema变量中加入手动设置的字段，来为该API接口添加一些手动设置的文档内容。

5.生成文档

在完成以上的步骤后，可以通过以下命令生成文档：

python manage.py generateschema --file schema.yml

这将会生成一个名为schema.yml的文档。若需要其他格式的文档，可以将schema.yml文件扩展名调整为对应的扩展名，例如.json、.md等。

6.查看文档

可以通过以下命令在终端中查看文档：

python manage.py runserver

并在浏览器中输入http://127.0.0.1:8000/docs/来查看生成的文档。

以上就是Django Rest Framework生成API文档的详细攻略。

接下来我将给出两条生成API文档的示例说明。

示例1

以下是一个获取用户列表的API接口文档：

from rest_framework import generics, serializers

class UserSerializer(serializers.ModelSerializer):
    """用户序列化器"""
    class Meta:
        model = User
        fields = ('id', 'username')

class UserList(generics.ListAPIView):
    """获取用户列表"""
    serializer_class = UserSerializer

    def get_queryset(self):
        return User.objects.all()

在UserList类上方的文档注释中，我们可以使用三引号写出API接口的简要描述和更具体的描述，而在UserSerializer类上方的文档注释中，则可以写出该序列化器的功能描述。

示例2

以下是一个创建新用户的API接口文档：

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.schemas import AutoSchema

class UserAddView(APIView):
    """注册新用户"""
    schema = AutoSchema(
        manual_fields=[
            coreapi.Field(
                "username",
                required=True,
                location="form",
                schema=coreschema.String(
                    title="用户名",
                    description="用户名应该以英文字母或数字开头，由英文字母、数字、下划线、横杠组成，长度最少为6个字符。",
                    pattern=r"^[a-zA-Z0-9][a-zA-Z0-9_-]{5,}$",
                ),
            ),
            coreapi.Field(
                "password",
                required=True,
                location="form",
                schema=coreschema.String(
                    title="密码",
                    description="密码应该至少由6个字符组成。",
                    pattern=r"^.{6,}$",
                ),
            ),
        ]
    )

    def post(self, request):
        """
        创建新用户

        - **username**: 用户名，应该以英文字母或数字开头，由英文字母、数字、下划线、横杠组成，长度最少为6个字符。
        - **password**: 密码，至少由6个字符组成。

        """

        username = request.data.get("username")
        password = request.data.get("password")

        # 创建新用户代码

        return Response(status=201, data={"message": "新用户已创建。"})

在UserAddView类上方的文档注释中，我们可以使用三引号写出API接口的简要描述和更具体的描述，而在schema变量中，则可以设置手动添加的一些字段，以添加需要的文档内容。