如何在Django Rest Framework中创建无需迁移的伪模型用于Swagger

1. 先搞定基础配置 #

确保已经安装DRF和drf-spectacular：

pip install djangorestframework drf-spectacular

然后在项目的settings.py里做如下配置：

INSTALLED_APPS = [
    # 其他内置app
    'rest_framework',
    'drf_spectacular',
]

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

SPECTACULAR_SETTINGS = {
    'TITLE': '你的API契约文档',
    'DESCRIPTION': '无数据库依赖的API接口定义',
    'VERSION': '1.0.0',
}

2. 用Serializer定义数据结构（替代数据库模型） #

不用写Django的Model，直接用DRF的普通Serializer来定义请求参数和响应数据的结构，完全脱离数据库。比如在serializers.py里：

from rest_framework import serializers

class UserRequestSerializer(serializers.Serializer):
    username = serializers.CharField(max_length=50, help_text='用户名')
    email = serializers.EmailField(help_text='邮箱')
    age = serializers.IntegerField(min_value=18, help_text='年龄')

class UserResponseSerializer(serializers.Serializer):
    id = serializers.IntegerField(help_text='用户ID')
    username = serializers.CharField(help_text='用户名')
    email = serializers.EmailField(help_text='邮箱')
    create_time = serializers.DateTimeField(help_text='创建时间')

3. 编写无数据库操作的视图 #

用DRF的视图类或函数视图，不需要关联任何数据库操作，只需要处理请求并返回模拟响应。这里推荐用drf-spectacular的@extend_schema装饰器来明确指定请求和响应的Serializer，让Swagger识别更准确。

函数视图示例 #

在views.py里：

from rest_framework.decorators import api_view
from rest_framework.response import Response
from drf_spectacular.utils import extend_schema
from .serializers import UserRequestSerializer, UserResponseSerializer
from datetime import datetime

@extend_schema(
    request=UserRequestSerializer,
    responses={201: UserResponseSerializer},
    summary='创建用户（模拟）',
    description='仅展示API契约，不实际存储数据'
)
@api_view(['POST'])
def create_user(request):
    # 验证请求参数（可选，用于模拟真实接口的参数校验逻辑）
    serializer = UserRequestSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)
    
    # 返回模拟的响应数据
    mock_response = {
        'id': 1001,
        'username': serializer.validated_data['username'],
        'email': serializer.validated_data['email'],
        'create_time': datetime.now()
    }
    return Response(mock_response, status=201)

@extend_schema(
    responses={200: UserResponseSerializer(many=True)},
    summary='获取用户列表（模拟）'
)
@api_view(['GET'])
def list_users(request):
    mock_users = [
        {
            'id': 1001,
            'username': 'test_user1',
            'email': 'test1@example.com',
            'create_time': datetime.now()
        },
        {
            'id': 1002,
            'username': 'test_user2',
            'email': 'test2@example.com',
            'create_time': datetime.now()
        }
    ]
    serializer = UserResponseSerializer(mock_users, many=True)
    return Response(serializer.data)

类视图示例 #

如果习惯用类视图，写法类似：

from rest_framework.views import APIView
from rest_framework.response import Response
from drf_spectacular.utils import extend_schema
from .serializers import UserResponseSerializer
from datetime import datetime

class UserListView(APIView):
    @extend_schema(
        responses={200: UserResponseSerializer(many=True)},
        summary='获取用户列表（类视图版）'
    )
    def get(self, request):
        mock_users = [
            {'id': 1001, 'username': 'test1', 'email': 'test1@example.com', 'create_time': datetime.now()},
            {'id': 1002, 'username': 'test2', 'email': 'test2@example.com', 'create_time': datetime.now()}
        ]
        serializer = UserResponseSerializer(mock_users, many=True)
        return Response(serializer.data)

4. 注册路由 #

在项目的urls.py里添加视图路由和Swagger文档路由：

from django.urls import path
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
from . import views

urlpatterns = [
    # API接口路由
    path('api/users/', views.list_users, name='user-list'),
    path('api/users/create/', views.create_user, name='user-create'),
    path('api/users/class/', views.UserListView.as_view(), name='user-list-class'),
    
    # Swagger文档路由
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
]

5. 启动项目查看效果 #

直接启动Django服务，不需要执行migrate命令（因为没建任何数据库模型）：

python manage.py runserver

访问http://localhost:8000/api/docs/就能看到Swagger UI，里面会展示你定义的所有接口的请求参数、响应结构，完全不需要数据库支持。

内容的提问来源于stack exchange，提问作者Ahmad Ordikhani