django自动添加接口文档

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


一、方案选择与安装

1. 方案对比
库名 维护状态 支持规范 功能特点
django-rest-swagger 已弃用 Swagger 2.0 旧项目兼容,文档生成简单
drf-yasg 活跃维护 OpenAPI 3.0 功能强大,支持更详细的配置
2. 安装推荐库(drf-yasg)
bash 复制代码
# 安装 drf-yasg(推荐)
pip install drf-yasg

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

二、配置 drf-yasg 生成接口文档(推荐)

1. 配置 settings.py
python 复制代码
# settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',
    'drf_yasg',  # 添加 drf-yasg
]

# 可选:配置 DRF 的默认权限(按需设置)
REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.AllowAny',
    ]
}
2. 配置 URL 路由
python 复制代码
# 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')),
]
3. 为视图添加文档注释

在视图(如 views.py)中使用装饰器或 YAML 注释描述接口:

python 复制代码
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": []})
4. 访问文档

Swagger UI : http://localhost:8000/swagger/

ReDoc : http://localhost:8000/redoc/


三、使用旧版 django-rest-swagger(不推荐)

1. 配置 settings.py
python 复制代码
# 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 路由
python 复制代码
# 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 格式):

python 复制代码
class UserListView(APIView):
    def get(self, request):
        """
        获取用户列表

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

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


四、常见问题与优化

1. 文档不显示接口

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

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

2. 认证配置

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

配置 (在 settings.py 中):

python 复制代码
SWAGGER_SETTINGS = {
    'LOGIN_URL': '/admin/login/',  # 登录地址
    'LOGOUT_URL': '/admin/logout/',
    'USE_SESSION_AUTH': True,
}
3. 自定义文档样式

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

python 复制代码
schema_view = get_schema_view(
    ...
    patterns=[...],  # 指定要包含的路由
    generator_class='myapp.schemas.CustomSchemaGenerator',  # 自定义生成器
)
4. 隐藏特定接口

使用 drf_yasg:

python 复制代码
@swagger_auto_schema(auto_schema=None)
def my_view(request):
    ...

五、总结

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

核心步骤

  1. 安装库并配置 settings.pyurls.py
  2. 通过装饰器或注释为视图添加接口描述。
  3. 访问 /swagger/ 查看文档。
    注意事项
    • 确保视图继承自 DRF 的基类(如 APIView)。
    • 若接口涉及认证(如 JWT),需在文档中配置安全策略。
相关推荐
一屉大大大花卷31 分钟前
初识Neo4j之入门介绍(一)
数据库·neo4j
周胡杰1 小时前
鸿蒙arkts使用关系型数据库,使用DB Browser for SQLite连接和查看数据库数据?使用TaskPool进行频繁数据库操作
前端·数据库·华为·harmonyos·鸿蒙·鸿蒙系统
wkj0011 小时前
navicate如何设置数据库引擎
数据库·mysql
赵渝强老师1 小时前
【赵渝强老师】Oracle RMAN的目录数据库
数据库·oracle
暖暖木头1 小时前
Oracle注释详解
数据库·oracle
御控工业物联网1 小时前
御控网关如何实现MQTT、MODBUS、OPCUA、SQL、HTTP之间协议转换
数据库·sql·http
GJCTYU3 小时前
spring中@Transactional注解和事务的实战理解附代码
数据库·spring boot·后端·spring·oracle·mybatis
MicroTech20253 小时前
微算法科技(NASDAQ: MLGO)探索Grover量子搜索算法,利用量子叠加和干涉原理,实现在无序数据库中快速定位目标信息的效果。
数据库·科技·算法
Code季风3 小时前
SQL关键字快速入门:CASE 实现条件逻辑
javascript·数据库·sql
weixin_478689763 小时前
操作系统【2】【内存管理】【虚拟内存】【参考小林code】
数据库·nosql