当前位置: 首页 > article >正文

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)
# 安装 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/', 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, 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 Response({"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,功能更强大且维护活跃。
核心步骤

  1. 安装库并配置 settings.pyurls.py
  2. 通过装饰器或注释为视图添加接口描述。
  3. 访问 /swagger/ 查看文档。
    注意事项
    • 确保视图继承自 DRF 的基类(如 APIView)。
    • 若接口涉及认证(如 JWT),需在文档中配置安全策略。

http://www.kler.cn/a/589072.html

相关文章:

  • Blender选择循环边/循环面技巧
  • 需求分析、定义、验证、变更、跟踪(高软47)
  • 第十六届蓝桥杯康复训练--1
  • Java实体类转JSON时如何避免null值变成“null“?
  • 现成的管理系统页面,直接可以使用,粘贴就行
  • Selenium Manager和webdriver manager的区别与联系
  • 【数学建模】一致矩阵的应用及其在层次分析法(AHP)中的性质
  • Gartner发布量子网络安全策略指南:2030年量子计算将能够破坏传统的加密算法
  • 安装教程整理 docker linux 虚拟机
  • MySQL时间溢出原理、影响与解决方案
  • NVIDIA Jetson上docker报错 can‘t initialize iptables table `raw‘
  • Unity Timeline 扩展
  • Unity学习日志4
  • vscode打不开
  • Pytest深度集成Playwright让测试自动化变得轻松简单
  • Cisdem Video Converter for Mac v8.4.1 视频格式转换 支持M、Intel芯片
  • Java 常用工具类大全:高频工具类及代码示例(后续继续补充)
  • 区块链与去中心化技术
  • 基于SpringBoot的公司财务管理系统+LW示例参考
  • 工作记录 2017-01-06