Django 結合 ReDoc API 文件編寫

先前介紹 Swagger 可視化的 API 文件，允許直接在瀏覽器上查看 API 文檔，並且可以進行 API 測試，而ReDoc 的設計比較簡潔，適合用來閱讀 API 文件，但不像 Swagger UI 那樣支援直接測試 API。

引入方式同Swagger，可參考編寫Swagger API文件引入。

• /schema/ 提供原始的 OpenAPI JSON Schema，供 Swagger、ReDoc 或其他工具解析。
• /swagger/ 提供互動式 API 文檔，允許發送 API 請求。
• /redoc/ 提供簡潔的 API 文件，適合閱讀但不能直接測試 API。

# urls.py

from drf_spectacular.views import (
    SpectacularAPIView,
    SpectacularRedocView,
    SpectacularSwaggerView,
)

from django.urls import path, include

urlpatterns = [
    path("", include("api.urls")),
]

urlpatterns += [
    path("schema/", SpectacularAPIView.as_view(), name="schema"),
    path(
        "swagger/",
        SpectacularSwaggerView.as_view(url_name="schema"),
        name="schema-swagger-ui",
    ),
    path(
        "redoc/",
        SpectacularRedocView.as_view(url_name="schema"),
        name="schema-redoc",
    ),
]

根據對應網址輸入 http://localhost:8000/redoc/ 察看Redoc API文檔。

左半部為API 、中間為詳細文件說明、右半部為接口與回應訊息

在Django中，可透過 View、Filter、Serializer、Model 等 help_Text 加入說明，使 ReDoc 加入 Require 等標註。

ex : 在 Filter 與 Serializer 、Mixin 加入說明。

# filter.py

class PermissionExpFilter(FilterSet):
    employee_name = django_filters.CharFilter(required=False,
 field_name='employee_name', 
 lookup_expr='icontains',
 help_text="測試用employee_name_20250309") # 加入說明

# Serializer.py
class PermissionExpSerializer(serializers.ModelSerializer):
    employee_name = serializers.CharField(max_length=255,
 required=True, # Redoc 會以紅色標註 Required 欄位
help_text="測試用employee_name_20250309") # 加入說明

# Views.py 掛上 schema
from utils.swagger import swagger_model_viewset_extend_schema
@swagger_model_viewset_extend_schema(name="PermissionExp")
class PermissionExpViewSet(PermissionExpMixin,ModelViewSet):
    queryset = PermissionExpModel.objects.all()
    serializer_class = PermissionExpSerializer
    filterset_class = PermissionExpFilter

前端可透過該文件了解對接需求與欄位說明。

除了欄位說明外，也可編輯 Response 回應格式，可透過extend_schema編寫回應格式，需要批量套用API時可使用Mixin模式。

class CustomSchemaMixin:
    """
    Mixin 用於統一 API 文件 (Swagger/ReDoc) 的回應格式
    """
@extend_schema(
        responses={
            200: OpenApiResponse(
                response=None,
                description="成功獲取列表",
                examples=[
                    {
                        "status": "success",
                        "code": 200,
                        "message": "獲取權限列表成功",
                        "data": []
                    }
                ],
            ),
            400: OpenApiResponse(
                response=None,
                description="請求格式錯誤",
                examples=[
                    {
                        "status": "error",
                        "code": 400,
                        "message": "請求參數無效",
                        "errors": {"field_name": ["錯誤描述"]}
                    }
                ],
            ),
        }
    )

回應文件 :

透過該文件使前後端串接流程更加順利，加速整體開發專案流程。