django DRF 组件接口文档

自动生成接口文档

REST framework可以自动帮助我们生成接口文档。drf的接口文档多数以网页的方式呈现，自动接口文档能生成的是继承自APIView及其子类的视图。

coreapi

安装依赖

REST framewrok生成接口文档需要coreapi库的支持。

pip3 install coreapi

设置接口文档访问路径

在settings.py中配置接口文档的模块到项目中。

INSTALLED_APPS = [
 
    'coreapi',


]
REST_FRAMEWORK = {
    # 。。。 其他选项
    # 配置自动生成接口文档的模式
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema',
}

在总路由中添加接口文档路径。

文档路由对应的视图配置为rest_framework.documentation.include_docs_urls，

参数title为接口文档网站的标题。总路由urls.py，代码：

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='站点页面标题'))
]

http://127.0.0.1:8000/docs/

component\urls.py

from rest_framework.routers import DefaultRouter

router = DefaultRouter()
router.register("doc", views.DocumentAPIView, basename="doc")
urlpatterns += router.urls

component\views.py

class DocumentAPIView(ModelViewSet):
    """
    list: 获取所有学生信息
    create: 添加学生信息
    read: 查询一个学生信息
    update: 更新一个学生信息
    partial_update: 更新一个学生信息[部分字段]
    delete: 删除一个学生信息
    login: 学生登录
    """
    queryset = Student.objects.all()
    serializer_class = StudentModelSerializer

drfdemo\stuapi\models.py

加上help_text=

from django.db import models


# Create your models here.
class Student(models.Model):
    """学生信息"""
    name = models.CharField(max_length=255, verbose_name="姓名",help_text="姓名")
    sex = models.BooleanField(default=True, verbose_name="性别",help_text="性别")
    age = models.IntegerField(verbose_name="年龄",help_text="年龄")
    classmate = models.CharField(db_column="class", max_length=5, verbose_name="班级",help_text="班级编号为3个数字组成")
    description = models.TextField(max_length=1000, null=True, blank=True, verbose_name="个性签名")

    class Meta:
        db_table = "tb_student"
        verbose_name = "学生"
        verbose_name_plural = verbose_name

    def __str__(self):
        return str(self.__dict__)

drfdemo\stuapi\models.py

from django.db import models


# Create your models here.
class Student(models.Model):
    """学生信息"""
    # help_text 提供给接口文档中显示当前字段的意义的
    name = models.CharField(max_length=255, verbose_name="姓名", help_text="姓名")
    sex = models.BooleanField(default=True, verbose_name="性别" ,help_text="性别")
    age = models.IntegerField(verbose_name="年龄", help_text="年龄")
    classmate = models.CharField(db_column="class", max_length=5, verbose_name="班级", help_text="班级编号为3个数字组成")
    description = models.TextField(max_length=1000, null=True, blank=True, verbose_name="个性签名", help_text="个性签名")

    class Meta:
        db_table = "tb_student"
        verbose_name = "学生"
        verbose_name_plural = verbose_name

文档描述说明的定义位置

1）单一方法的视图，可直接使用类视图的文档字符串，如

class StudentListView(ListAPIView):
    """
    返回所有学生信息
    """

2）包含多个方法的视图，在类视图的文档字符串中，分开方法定义，如

from rest_framework.generics import ListCreateAPIView
class DocumentAPIView(ListCreateAPIView):
    """
    get: 获取所有学生信息
    post: 添加学生信息
    """
    queryset = Student.objects.all()
    serializer_class = StudentModelSerializer
    
from rest_framework.generics import RetrieveUpdateDestroyAPIView
class Document1APIView(RetrieveUpdateDestroyAPIView):
    """
    get: 查询一个学生信息
    put: 更新一个学生信息
    patch: 更新一个学生信息[部分字段]
    delete: 删除一个学生信息
    """
    queryset = Student.objects.all()
    serializer_class = StudentModelSerializer

3）对于视图集ViewSet，在类视图的文档字符串中定义，但是应使用action名称区分，如

from rest_framework.decorators import action
from demo.serializers import StudentLoginModelSerializer

class DocumentAPIView(ModelViewSet):
    """
    list: 获取所有学生信息
    create: 添加学生信息
    read: 查询一个学生信息
    update: 更新一个学生信息
    partial_update: 更新一个学生信息[部分字段]
    delete: 删除一个学生信息
    login: 学生登录
    """
    queryset = Student.objects.all()

    def get_serializer_class(self):
        if self.action == "login":
            return StudentLoginModelSerializer
        return StudentModelSerializer
    
    @action(methods=["POST"], detail=False)
    def login(self, request):
        return Response("ok")

serializers.py，代码：

from rest_framework import serializers
from stuapi.models import Student
from .models import Course

class StudentModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = Student
        fields = "__all__"


class StudentLoginModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = Student
        fields = ["name", "age"]

class CourseModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = Course
        fields = "__all__"

stuapi/modes.py，代码：

from django.db import models


# Create your models here.
class Student(models.Model):
    """学生信息"""
    # help_text 提供给接口文档中显示当前字段的意义的
    name = models.CharField(max_length=255, verbose_name="姓名", help_text="姓名")
    sex = models.BooleanField(default=True, verbose_name="性别" ,help_text="性别")
    age = models.IntegerField(verbose_name="年龄", help_text="年龄")
    classmate = models.CharField(db_column="class", max_length=5, verbose_name="班级", help_text="班级编号为3个数字组成")
    description = models.TextField(max_length=1000, null=True, blank=True, verbose_name="个性签名", help_text="个性签名")

    class Meta:
        db_table = "tb_student"
        verbose_name = "学生"
        verbose_name_plural = verbose_name

urls.py，代码：

from django.urls import path, re_path
from . import views

urlpatterns = [
   # ..中间代码省略
]

from rest_framework.routers import DefaultRouter
router = DefaultRouter()
router.register("doc", views.DocumentAPIView, basename="doc")
urlpatterns += router.urls

访问接口文档网页

浏览器访问 127.0.0.1:8000/docs/，即可看到自动生成的接口文档。

两点说明：

1）视图集ViewSet中的retrieve名称，在接口文档网站中叫做read

2）参数的Description需要在模型类或序列化器类的字段中以help_text选项定义，如：

class Student(models.Model):
    ...
    age = models.IntegerField(default=0, verbose_name='年龄', help_text='年龄')
    ...

或

class StudentModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = Student
        fields = "__all__"
        extra_kwargs = {
            'classmate': {
                'help_text': '班级'
            }
        }

yasg

Swagger是一个规范和完整的自动化接口开发框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新。当接口有变动时，对应的接口文档也会自动更新。如：接口测试站点（http://httpbin.org/），也是利用Swagger来生成接口文档。

Swagger在线编辑器：https://editor.swagger.io/

官方文档：https://drf-yasg.readthedocs.io/en/stable/

Github：https://github.com/axnsan12/drf-yasg

安装

pip3 install drf-yasg

配置，settings.py，代码：

INSTALLED_APPS = [

    'drf_yasg',  # 接口文档drf_yasg

]

总路由，

"""drfdemo URL Configuration

The `urlpatterns` list routes URLs to views. For more information please see:
    https://docs.djangoproject.com/en/4.0/topics/http/urls/
Examples:
Function views
    1. Add an import:  from my_app import views
    2. Add a URL to urlpatterns:  path('', views.home, name='home')
Class-based views
    1. Add an import:  from other_app.views import Home
    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
Including another URLconf
    1. Import the include() function: from django.urls import include, path
    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
"""
from django.contrib import admin
from django.urls import path, include
from rest_framework.documentation import include_docs_urls


# yasg的视图配置类，用于生成a'pi
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# 接口文档的视图配置
schema_view = get_schema_view(
    openapi.Info(
        title="drf接口文档",  # 站点标题，必填
        default_version='v1.0,0',  # api版本，必填
        description="描述信息",  # 站点描述
        terms_of_service='htttp://www.moluo.net/',   # 团队博客网址
        contact=openapi.Contact(name="墨落", url="htttp://www.moluo.net/", email="649641514@qq.com"), # 联系邮箱地址
        license=openapi.License(name="开源协议名称", url="开源协议网地") # 协议
    ),
    public=True, # 是否外部站点
    # permission_classes=(rest_framework.permissions.AllowAny)  # 权限类
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('doc/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger'),
    path('docs/', include_docs_urls(title='公司项目名')),
    path('api/', include("stuapi.urls")),
    path('api/', include("students.urls")),
    path('sers/', include("sers.urls")),
    path("req/", include("req.urls")),
    path("demo/", include("demo.urls")),
    path("component/", include("component.urls")),
]

http://127.0.0.1:8000/doc/，访问效果：

posted @ 2025-06-24 15:07 minger_lcm 阅读(33) 评论(0) 收藏举报

刷新页面返回顶部

django DRF 组件 接口文档