Django集成Swagger的两种实现方案全指南_Python

一、前言

概述

在前后端分离开发中，api 文档的重要性不言而喻。swagger（现更名为 openapi）作为主流的 api 文档生成工具，能自动生成交互式文档，极大提升开发效率。本文将介绍两种在 django 项目中集成 swagger 的实用方案，帮助开发者快速搭建完善的 api 文档系统。

什么是 swagger/openapi

swagger 是一套用于描述、生成、消费和可视化 restful api 的规范和工具集，目前已演进为 openapi 规范：

swagger 2.0：支持 websockets、oauth2、文件上传等功能，提升了 api 描述的精确度
openapi 3.0：下一代规范，提供更严格的模式验证、更多数据类型支持和更好的扩展性

通过集成 swagger，开发者可以获得：

自动生成的交互式 api 文档
在线接口调试功能
标准化的 api 描述格式（json/yaml）
便于前后端协作和 api 版本管理

两种方案对比

特性	drf-yasg	drf-spectacular
规范支持	swagger 2.0	openapi 3.0
功能丰富度	基础功能完善	高级功能更丰富
可定制性	中等	高
学习曲线	平缓	稍陡
推荐场景	简单项目快速集成	复杂项目、需要高级定制

二、方案一：使用 drf-yasg（支持 swagger 2.0）

工具介绍

drf-yasg 是基于 django rest framework (drf) 的 api 文档生成工具，专注于 swagger 2.0 规范，具有以下特点：

动态生成 swagger ui，支持多种主题
可自定义文档样式和内容
支持隐藏指定字段、添加额外参数等高级功能

安装步骤

安装

pip install -u drf-yasg

配置settings.py：在 installed_apps 中添加相关应用

installed_apps = [
   # ...
   'django.contrib.staticfiles',  # 用于提供 swagger ui 的静态文件
   'drf_yasg',
   # ...
]

配置urls.py：添加 swagger 相关路由

from django.urls import re_path
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# 配置 api 文档基本信息
schema_view = get_schema_view(
   openapi.info(
      title="项目 api",
      default_version='v1',
      description="api 接口文档描述",
      terms_of_service="https://www.example.com/terms/",
      contact=openapi.contact(email="contact@example.com"),
      license=openapi.license(name="mit license"),
   ),
   public=true,
   permission_classes=(permissions.allowany,),  # 允许任何人访问文档
)

# 添加 url 路由
urlpatterns = [
   # ...
   # 文档 json/yaml 下载
   path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   # swagger ui 页面
   path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
   # redoc 页面
   path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
   # ...
]

查看效果

启动 django 项目后，通过以下地址访问文档：

swagger ui 界面：http://localhost:8000/swagger/

redoc 界面：http://localhost:8000/redoc/

下载 json 格式文档：http://localhost:8000/swagger.json

下载 yaml 格式文档：http://localhost:8000/swagger.yaml

三、方案二：使用 drf-spectacular（支持 openapi 3.0）

工具介绍

drf-spectacular 是新一代 api 文档生成工具，支持 openapi 3.0 规范，具有以下优势：

更强的可扩展性和可定制性
支持客户端代码生成
兼容多种 drf 插件
提供更丰富的文档装饰器

参考资料： drf-spectacular 官方文档

安装步骤

安装

pip install drf-spectacular
pip install drf-spectacular[sidecar] # 安装内置 ui 资源（推荐）

配置 settings.py：点击查看完整代码

installed_apps = [
	# ...
    'drf_spectacular',
    'drf_spectacular_sidecar',  # 内置 ui 资源
    # ...
]

# 配置 drf
rest_framework = {
    # openapi 文档
    'default_schema_class': 'drf_spectacular.openapi.autoschema',
}

### drf-spectacular openapi 文档配置
spectacular_settings = {
    "swagger_ui_dist": "sidecar",  # 使用内置 ui
    "swagger_ui_favicon_href": "sidecar",
    "title": "marsmgn api",
    "description": "火星信息平台接口文档",
    "version": "1.0.0",
    "serve_include_schema": false,  # 不在文档中包含 schema 本身
}

配置 urls.py：点击查看完整代码

from drf_spectacular.views import spectacularapiview, spectacularredocview, spectacularswaggerview

urlpatterns = [
    #...
    # api schema 生成端点
    path('api/schema/', spectacularapiview.as_view(), name='schema'),
    # swagger ui 界面
    path('api/schema/swagger-ui/', spectacularswaggerview.as_view(url_name='schema'), name='swagger-ui'),
    # redoc 界面
    path('api/schema/redoc/', spectacularredocview.as_view(url_name='schema'), name='redoc'),
    #...
]

查看效果

启动 django 项目后，通过以下地址访问 swagger ui 界面：http://127.0.0.1:8000/api/schema/swagger-ui

四、drf-spectacular 高级使用技巧

字段注释

文档描述优先从序列化器 / 模型的 help_text 提取：

class systempost(models.model):
    id = models.bigautofield(primary_key=true, help_text="岗位id")
    code = models.charfield(
        max_length=64,
        help_text="岗位编码",  # 会显示在文档中
    )

接口说明

使用 @extend_schema 装饰器自定义接口描述：

from drf_spectacular.utils import extend_schema

@extend_schema(summary="创建岗位", description="自定义接口详细说明")
@action(methods=["post"], detail=false, url_path="create")
def create_post(self, request, *args, **kwargs):
    return self.custom_create(request, *args, **kwargs)

接口分组

通过 tags 参数对接口进行分组：

@extend_schema(tags=["管理后台-system-岗位"])
class postviewset(customviewset):
    queryset = systempost.objects.all()
    filterset_class = systempostfilter

请求与响应参数定义

定义响应参数示例

from drf_spectacular.utils import extend_schema, openapiresponse
from drf_spectacular.types import openapitypes

@extend_schema(
    responses={
        200: openapiresponse(
            description="操作成功",
            response={
                "type": "object",
                "properties": {
                    "code": {"type": "integer", "example": 0},
                    "data": {"type": "boolean", "example": true},
                    "msg": {"type": "string", "example": ""}
                }
            }
        )
    }
)
def delete_post(self, request, *args, **kwargs):
    """删除岗位"""
    return response({"code": 0, "data": true, "msg": ""}, status=200)

到此这篇关于django集成swagger的两种实现方案全指南的文章就介绍到这了,更多相关django集成swagger内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！