# 安裝 drf-yasg（推薦）
pip install drf-yasg

# 或安裝舊版 django-rest-swagger（不推薦）
# pip install django-rest-swagger==2.2.0

# settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',
    'drf_yasg',  # 添加 drf-yasg
]

# 可選：配置 DRF 的默認權(quán)限（按需設(shè)置）
REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.AllowAny',
    ]
}

# urls.py
from django.urls import path, include
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# 定義 Swagger 文檔視圖
schema_view = get_schema_view(
    openapi.Info(
        title="API 文檔",
        default_version='v1',
        description="項目接口文檔",
        terms_of_service="https://example.com/terms/",
        contact=openapi.Contact(email="contact@example.com"),
        license=openapi.License(name="MIT License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),  # 控制文檔訪問權(quán)限
)

urlpatterns = [
    # Swagger 文檔路由
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='swagger-ui'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='redoc'),
    
    # 其他 API 路由
    path('api/', include('myapp.urls')),
]

from drf_yasg.utils import swagger_auto_schema
from rest_framework.views import APIView
from rest_framework.response import Response

class UserListView(APIView):
    @swagger_auto_schema(
        operation_description="獲取用戶列表",
        manual_parameters=[
            openapi.Parameter(
                'page', 
                openapi.IN_QUERY, 
                description="頁碼", 
                type=openapi.TYPE_INTEGER
            ),
        ],
        responses={200: '成功獲取用戶列表'}
    )
    def get(self, request):
        return Response({"users": []})

# settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',
    'rest_framework_swagger',  # 添加 django-rest-swagger
]

# 配置 Swagger 設(shè)置
SWAGGER_SETTINGS = {
    'SECURITY_DEFINITIONS': {
        'basic': {
            'type': 'basic'
        }
    },
    'USE_SESSION_AUTH': False,  # 是否啟用 Django 的 Session 認證
}

# urls.py
from django.urls import path
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer

schema_view = get_schema_view(
    title="API 文檔",
    renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer]
)

urlpatterns = [
    path('swagger/', schema_view, name='swagger'),
    path('api/', include('myapp.urls')),
]

class UserListView(APIView):
    def get(self, request):
        """
        獲取用戶列表

        ---
        parameters:
            - name: page
              in: query
              type: integer
              required: false
              description: 頁碼
        responses:
            200:
                description: 成功返回用戶列表
        """
        return Response({"users": []})

SWAGGER_SETTINGS = {
    'LOGIN_URL': '/admin/login/',  # 登錄地址
    'LOGOUT_URL': '/admin/logout/',
    'USE_SESSION_AUTH': True,
}

schema_view = get_schema_view(
    ...
    patterns=[...],  # 指定要包含的路由
    generator_class='myapp.schemas.CustomSchemaGenerator',  # 自定義生成器
)

@swagger_auto_schema(auto_schema=None)
def my_view(request):
    ...