django自动添加接口文档的实现

# 安装 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 的默认权限（按需设置）
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,),  # 控制文档访问权限
)

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 设置
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):
    ...