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

目录

• 一、方案选择与安装
• 1. 方案对比
• 2. 安装推荐库（drf-yasg）
• 二、配置 drf-yasg 生成接口文档（推荐）
• 1. 配置 settings.py
• 2. 配置 URL 路由
• 3. 为视图添加文档注释
• 4. 访问文档
• 三、使用旧版 django-rest-swagger（不推荐）
• 1. 配置 settings.py
• 2. 配置 URL 路由
• 3. 为视图添加注释
• 4. 访问文档
• 四、常见问题与优化
• 1. 文档不显示接口
• 2. 认证配置
• 3. 自定义文档样式
• 4. 隐藏特定接口
• 五、总结

以下是使用 Django 和 django-rest-swagger（或替代方案 drf-yasg）生成 API 接口文档的详细指南。由于 django-rest-swagger 已停止维护，推荐使用 drf-yasg（支持 Swagger 2.0 和 OpenAPI 3.0），但两种方法均会说明：

一、方案选择与安装

1. 方案对比

2. 安装推荐库（drf-yasg）

# 安装 drf-yasg（推荐）
pip install drf-yasg

# 或安装旧版 django-rest-swagger（不推荐）
# pip install django-rest-swagger==2.2.0

二、配置 drf-yasg 生成接口文档（推荐）

1. 配置 settings.py

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

# 可选：配置 DRF 的默认权限（按需设置）
REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES':编程 [
        'rest_framework.permissions.AllowAny',
    ]
}

2. 配置 URL 路由

# 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/'python, include('myapp.urls')),
]

3. 为视图添加文档注释

在视图（如 views.py）中使用装饰器或 YAML 注释描述接口：

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,php request):
        return Response({"users": []})

4. 访问文档

• Swagger UI: http://localhost:8000/swagger/• ReDoc: http://localhost:8000/redoc/

三、使用旧版 django-rest-swagger（不推荐）

1. 配置 settings.py

# 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 认证
}

2. 配置 URL 路由

# 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')),
]

3. 为视图添加注释

在视图类或函数中使用文档字符串（YAML 格式）：

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

        ---
        parameters:
            - name: page
              in: query
              type: integer
              required: false
              description: 页码
        responses:
            200:
                description: 成功返回用户列表
        """
        return Responjsse({"users": []})

4. 访问文档

• 访问 http://localhost:8000/swagger/

四、常见问题与优化

1. 文档不显示接口

• 原因: 视图未继承 APIView 或未配置路由。

• 解决: 确保所有接口使用 DRF 的视图类（如 APIView, ViewSet），并正确注册到路由。

2. 认证配置

• 场景: 需要登录才能访问 Swagger 文档。

• 配置（在 settings.py 中）：

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

3. 自定义文档样式

• 方法: 覆盖默认模板或使用 drf-yasg 的扩展参数：

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

4. 隐藏特定接口

• 使用 drf_yasg:

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

五、总结

推荐方案: 使用 drf-yasg，功能更强大且维护活跃。

核心步骤：

• 安装库并配置php settings.py 和 urls.py。
• 通过装饰器或注释为视图添加接口描述。
• 访问 /swagger/ 查看文档。

  • 注意事项：

  • 确保视图继承自 DRF 的基类（如 APIView）。

  • 若接口涉及认证（如 JWT），需在文档中配置安全策略。

到此这篇关于django自动添加接口文档的实现的文章就介绍到这了,更多相关django自动接口文档内容请搜索编程客栈(www.devze.com)以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程客栈(www.devze.com)！