django-rest-swagger如何记录API

Django REST Swagger API文档记录指南

基础概念

Django REST Swagger是一个用于为Django REST Framework API生成交互式文档的工具。它基于Swagger/OpenAPI规范，可以自动从你的API代码中生成文档。

安装与配置

首先安装必要的包：

pip install django-rest-swagger

然后在settings.py中添加：

INSTALLED_APPS = [
    ...
    'rest_framework',
    'rest_framework_swagger',
    ...
]

基本使用

1. 添加URL路由

在urls.py中添加：

from rest_framework_swagger.views import get_swagger_view

schema_view = get_swagger_view(title='API Documentation')

urlpatterns = [
    ...
    path('docs/', schema_view),
    ...
]

2. 视图函数文档

使用标准的Django REST Framework文档字符串格式：

class UserList(APIView):
    """
    get:
    返回所有用户列表
    
    post:
    创建新用户
    
    put:
    更新用户信息
    """
    def get(self, request):
        ...

3. 序列化器字段文档

在序列化器字段中使用help_text参数：

class UserSerializer(serializers.ModelSerializer):
    username = serializers.CharField(help_text="用户的唯一标识")
    email = serializers.EmailField(help_text="用户的电子邮箱地址")
    
    class Meta:
        model = User
        fields = ['username', 'email']

高级功能

1. 参数文档

使用@swagger_auto_schema装饰器详细描述参数：

from drf_yasg.utils import swagger_auto_schema

class UserList(APIView):
    @swagger_auto_schema(
        manual_parameters=[
            openapi.Parameter(
                'username',
                openapi.IN_QUERY,
                description="按用户名筛选",
                type=openapi.TYPE_STRING
            ),
        ],
        responses={200: UserSerializer(many=True)}
    )
    def get(self, request):
        ...

2. 响应文档

@swagger_auto_schema(
    responses={
        200: openapi.Response('成功响应', UserSerializer),
        400: '无效请求',
        404: '用户不存在'
    }
)
def get(self, request, pk):
    ...

3. 请求体文档

@swagger_auto_schema(
    request_body=UserSerializer,
    responses={201: '创建成功', 400: '无效数据'}
)
def post(self, request):
    ...

常见问题解决

1. 文档不显示

检查rest_framework_swagger是否在INSTALLED_APPS中
确保URL配置正确
检查是否有权限限制

2. 文档内容不完整

确保所有视图都有适当的文档字符串
检查序列化器字段是否有help_text
对于复杂API，使用@swagger_auto_schema装饰器

3. 样式问题

如果样式加载不正常，可能是静态文件问题：

STATIC_URL = '/static/'

替代方案

如果遇到问题，可以考虑使用drf-yasg(Yet Another Swagger Generator)，它是Django REST Swagger的现代替代品：

pip install drf-yasg

配置方式类似但功能更强大，支持OpenAPI 3.0规范。

最佳实践

为每个API端点编写清晰的文档字符串
为所有序列化器字段添加help_text
使用@swagger_auto_schema装饰复杂API
保持文档与代码同步更新
考虑将API文档作为开发流程的一部分