Django Swagger文档库drf-spectacular

一、概述

drf-spectacular 是一个为 Django REST Framework (DRF) 设计的 OpenAPI 3.0 和 3.1 规范的生成器。它旨在提供既理智又灵活的方式来创建 API 文档，主要实现以下三个目标：

从 DRF 中提取尽可能多的 schema 信息
提供灵活性，使 schema 在现实世界中可用(不仅仅是示例)
生成一个与最流行的客户端生成器兼容的 schema

官网：

https://drf-spectacular.readthedocs.io/en/latest/

先来看一个效果图吧

 用户详情

 用户更新

 接下来会详细介绍，如何实现

二、安装

环境说明

python：3.12.3

django：5.0.7

djangorestframework：3.15.2
drf-spectacular：0.28.0

三、配置

修改django项目中的settings.py

注册app

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'myapp',
    'drf_spectacular',  # 接口文档 swagger
    'drf_spectacular_sidecar', # 接口文档 swagger-ui
]

将 AutoSchema 注册到 DRF 中

最后一行添加

REST_FRAMEWORK = {
    # YOUR SETTINGS
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

修改一些默认配置

最后一行添加

# drf-spectacular  配置
SPECTACULAR_SETTINGS = {
    'TITLE': '平台的API',
    'DESCRIPTION': 'Your project description',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
    # OTHER SETTINGS
    'SWAGGER_UI_DIST': 'SIDECAR',  # shorthand to use the sidecar instead
    'SWAGGER_UI_FAVICON_HREF': 'SIDECAR',
    'REDOC_DIST': 'SIDECAR',
}

添加路由

在项目主目录的url中添加

from django.urls import path

from rest_framework.routers import DefaultRouter
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView

urlpatterns = [
    # YOUR PATTERNS
    path('doc/schema/', SpectacularAPIView.as_view(), name='schema'), # schema的配置文件的路由，下面两个ui也是根据这个配置文件来生成的
    path('doc/swagger/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'), # swagger-ui的路由
    path('doc/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'), # redoc的路由
]

四、视图函数配置

完整视图函数如下：

from django.shortcuts import render
from rest_framework.response import Response
from rest_framework import viewsets
from rest_framework import sta