如何在 Django REST Framework 中自动创建 API 文档？

Django REST Framework (DRF) 是 Django 的一个扩展框架，专门用于快速搭建 RESTful API。与 Django 一样，DRF 提供了丰富的功能集和易于使用的模板，能够帮助开发者快速创建高质量的 API。

但是，在编写 API 的时候，我们通常需要编写 API 文档。这份文档需要包含 API 的所有信息，例如接口名称、输入数据、响应数据等等。因此，在这篇文章中，我们将介绍如何使用 DRF 的自动化 API 文档功能快速创建 API 文档。

安装依赖

在使用 DRF 的自动化 API 文档功能之前，你需要安装以下依赖：

• djangorestframework: DRF 的核心依赖库
• coreapi: DRF 自动化 API 文档的依赖库
• pyyaml: 一个 Python 库，用于将 YAML 格式转换为 Python 对象

你可以通过以下命令安装这些依赖：

pip install djangorestframework coreapi pyyaml

编写 API

在介绍如何创建自动化 API 文档之前，先介绍一下如何编写 API。

假设你正在创建一个博客网站，现在需要编写博客文章的 API。我们将创建一个 BlogPost 模型，并使用 DRF 的 ModelViewSet 快速创建简单的 API。代码如下：

# blog/models.py

from django.db import models


class BlogPost(models.Model):
    title = models.CharField(max_length=255)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)

# blog/serializers.py

from rest_framework import serializers
from .models import BlogPost


class BlogPostSerializer(serializers.ModelSerializer):
    class Meta:
        model = BlogPost
        fields = '__all__'

# blog/views.py

from rest_framework import viewsets
from .models import BlogPost
from .serializers import BlogPostSerializer


class BlogPostViewSet(viewsets.ModelViewSet):
    queryset = BlogPost.objects.all()
    serializer_class = BlogPostSerializer

# blog/urls.py

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import BlogPostViewSet

router = DefaultRouter()
router.register('', BlogPostViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

这是一个简单的 API，可以通过 GET、POST、PUT、DELETE 等 HTTP 请求来访问博客文章列表和详情页面。

创建 API 文档

创建 API 文档的方法有很多种，其中最常用的是使用 DRF 的自动化 API 文档功能。将这个功能应用到我们的例子中，可以在 BlogPostViewSet 中添加以下方法：

from rest_framework.documentation import include_docs_urls
from django.utils.decorators import method_decorator
from django.views.decorators.csrf import csrf_exempt

class BlogPostViewSet(viewsets.ModelViewSet):
    queryset = BlogPost.objects.all()
    serializer_class = BlogPostSerializer

    @method_decorator(csrf_exempt)
    def list(self, request):
        """
        获取博客文章列表
        """
        return super().list(request)

    @method_decorator(csrf_exempt)
    def retrieve(self, request, pk=None):
        """
        获取博客文章详情
        """
        return super().retrieve(request, pk)

    @method_decorator(csrf_exempt)
    def create(self, request):
        """
        创建博客文章
        """
        return super().create(request)

    @method_decorator(csrf_exempt)
    def update(self, request, pk=None):
        """
        更新博客文章
        """
        return super().update(request, pk)

    @method_decorator(csrf_exempt)
    def partial_update(self, request, pk=None):
        """
        部分更新博客文章
        """
        return super().partial_update(request, pk)

    @method_decorator(csrf_exempt)
    def destroy(self, request, pk=None):
        """
        删除博客文章
        """
        return super().destroy(request, pk)

    docs = include_docs_urls(title='博客 API 文档', public=False, permission_classes=[])

    def get_docs(self, request):
        return self.docs(request)

在上面的代码中，我们为 BlogPostViewSet 添加了 docs 方法，用于返回 API 文档页面。使用 @method_decorator 装饰器和 csrf_exempt 函数，可以避免 Django CSRF 保护机制对 POST/PUT/DELETE 请求的干扰。

最后，在 urls.py 中添加路由：

from .views import BlogPostViewSet

urlpatterns = [
    path('', include(BlogPostViewSet().docs))
]

运行 Django，访问 http://localhost:8000/api/docs/ 即可查看自动生成的 API 文档。

总结

本文介绍了如何在 Django REST Framework 中自动创建 API 文档。使用 DRF 自动化 API 文档功能，可以快速创建高质量的 API 文档，提高 API 的可读性和可维护性。如果你正在使用 DRF 编写 API，那么不妨试试这个功能吧！