当前位置: 首页 > article >正文

【后端】【django drf】django自动导出优雅的api文档的写法

Django DRF API 编写规范(包含 OpenAPI 生成规则)

为了确保 Django DRF API 代码的可维护性、可扩展性,同时生成清晰、规范、结构层次分明的 OpenAPI 文档,必须遵循以下规则。


一、使用 drf-spectacular 生成 OpenAPI 文档

(一)安装 drf-spectacular

pip install drf-spectacular

(二)配置 settings.py

INSTALLED_APPS = [
    'drf_spectacular',
    'rest_framework',
]

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

SPECTACULAR_SETTINGS = {
    'TITLE': "My API",
    'DESCRIPTION': "项目 API 文档",
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
    'SWAGGER_UI_SETTINGS': {
        'deepLinking': True,
        'defaultModelRendering': 'model',
        'defaultModelsExpandDepth': 2,
    },
}

(三)添加 OpenAPI 路由

from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView

urlpatterns = [
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('api/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]
  • 访问 /api/docs/:Swagger UI
  • 访问 /api/redoc/:ReDoc

二、编写清晰的 API 视图

(一)使用 @extend_schema 详细描述 API

from drf_spectacular.utils import extend_schema
from rest_framework.viewsets import ModelViewSet
from .models import User
from .serializers import UserSerializer

class UserViewSet(ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

    @extend_schema(
        summary="获取用户列表",
        description="返回所有用户的列表,支持分页。",
        responses={200: UserSerializer(many=True)}
    )
    def list(self, request, *args, **kwargs):
        return super().list(request, *args, **kwargs)
📌 规则
  1. @extend_schema(summary="简要说明", description="详细描述") 用于丰富 API 文档。
  2. responses={200: UserSerializer(many=True)} 确保文档显示正确的返回格式。

三、在 serializers.py 里优化文档

(一)使用 help_textverbose_name 提供字段说明

from rest_framework import serializers
from .models import User

class UserSerializer(serializers.ModelSerializer):
    username = serializers.CharField(help_text="用户名,唯一标识")
    email = serializers.EmailField(help_text="用户的电子邮箱地址")

    class Meta:
        model = User
        fields = ["id", "username", "email"]
📌 规则
  1. help_text:用于 API 文档中展示字段说明。
  2. verbose_name:如果模型里定义了,会自动生成为字段的描述。

四、使用 @extend_schema_viewViewSet 更清晰

如果 ViewSet 里的方法较多,每个方法都写 @extend_schema 会很冗余,可以直接给整个 ViewSet 统一定义:

from drf_spectacular.utils import extend_schema_view

@extend_schema_view(
    list=extend_schema(summary="获取用户列表"),
    retrieve=extend_schema(summary="获取单个用户详情"),
    create=extend_schema(summary="创建新用户"),
    update=extend_schema(summary="更新用户信息"),
    partial_update=extend_schema(summary="部分更新用户信息"),
    destroy=extend_schema(summary="删除用户"),
)
class UserViewSet(ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
📌 规则
  1. @extend_schema_view 统一管理 ViewSet 方法的文档信息,避免重复写 @extend_schema
  2. 适用于 ModelViewSet

五、给请求参数提供明确说明

(一)在 serializers.py 里定义 API 请求体

from drf_spectacular.utils import OpenApiExample, extend_schema
from rest_framework import serializers

class UserCreateSerializer(serializers.Serializer):
    username = serializers.CharField(help_text="用户的唯一标识")
    email = serializers.EmailField(help_text="用户的电子邮箱")
    password = serializers.CharField(write_only=True, help_text="密码,至少8位")

    class Meta:
        fields = ["username", "email", "password"]

(二)在 views.py 里使用

from drf_spectacular.utils import extend_schema

@extend_schema(
    request=UserCreateSerializer,
    responses={201: UserSerializer},
    examples=[
        OpenApiExample(
            name="示例用户",
            value={"username": "john_doe", "email": "john@example.com", "password": "securepassword"},
            request_only=True
        )
    ]
)
def create(self, request, *args, **kwargs):
    return super().create(request, *args, **kwargs)
📌 规则
  1. request=UserCreateSerializer 指定 API 需要的请求参数格式。
  2. examples 提供示例数据,方便前端查看。

六、使用 OpenApiParameter 定义查询参数

(一)示例

from drf_spectacular.utils import OpenApiParameter

@extend_schema(
    parameters=[
        OpenApiParameter(name="username", description="按照用户名筛选", required=False, type=str),
        OpenApiParameter(name="page", description="分页参数,默认为1", required=False, type=int),
    ],
    responses={200: UserSerializer(many=True)}
)
def list(self, request, *args, **kwargs):
    return super().list(request, *args, **kwargs)
📌 规则
  1. OpenApiParameter 用于 API 查询参数说明。
  2. description="说明" 确保前端易于理解。

七、示例 API 端点

最终效果(访问 /api/docs/

paths:
  /users/:
    get:
      summary: "获取用户列表"
      description: "返回所有用户的列表,支持分页"
      parameters:
        - name: username
          in: query
          description: "按照用户名筛选"
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: "分页参数,默认为1"
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: "成功获取用户列表"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
  /users/{id}/:
    get:
      summary: "获取单个用户详情"
      description: "返回指定 ID 的用户信息"
      responses:
        "200":
          description: "成功获取用户"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

总结

  1. drf-spectacular 是 Django DRF 生成 OpenAPI 文档的最佳选择
  2. 使用 @extend_schema 为 API 方法添加详细说明,避免自动生成的文档缺少描述。
  3. serializers.py 里使用 help_text 提供字段说明,提升可读性。
  4. 使用 @extend_schema_view 统一管理 ViewSet 的文档信息,减少重复代码。
  5. 使用 OpenApiParameter 明确查询参数,提升 API 交互性
  6. 提供 examples 示例,让前端更容易理解 API 请求结构

这样可以确保 API 文档清晰、可维护,方便前后端协作 🚀。

原文地址:https://blog.csdn.net/qq_59344127/article/details/146243285
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.kler.cn/a/584482.html

相关文章:

  • Ultravox:融合whisper+llama实现audio2text交互
  • ubuntu20.04
  • 汉桑科技IPO:潜藏两大风险 公众投资者权益或受损
  • 食品饮料制造行业的现状 内检实验室系统在食品饮料制造行业应用
  • 高效数据集成:金蝶云星空与管易云采购订单案例分析
  • 使用RabbitMQ实现流量削峰填谷
  • 【从零开始学习计算机科学】数据库系统(六)DBMS事务管理
  • 什么是物理信息神经网络PINN
  • 文件解析漏洞练习
  • Android app:layout_constraintHorizontal_bias=“0“属性详解
  • WPF 性能优化策略:提升应用的运行效率与流畅度
  • spring boot3.4.3+MybatisPlus3.5.5+swagger-ui2.7.0
  • 【GPT入门】第20课 文心千帆注册与API调用
  • 【工具变量】中国地级市科技金融试点政策名单数据(2000-2024年)
  • 【Academy】跨站点脚本 XSS ------ Cross-site scripting
  • uniapp APP使用web-view内嵌 h5 解决打包发版浏览器有缓存需要清除的问题
  • LLaMA:开放且高效的基础语言模型
  • 深度学习 模型和代码
  • mysql进阶——数据类型一篇详解
  • 在 Linux 64 位系统上安装 Oracle 11g R2 数据库的完整指南