【后端】【django】导出 API 文档的几种方法

在 Django 项目里,导出 API 文档是很常见的需求,一般可以借助第三方库来实现。

使用 drf-yasg 导出 Swagger/OpenAPI 格式文档

drf-yasg 是一个用于 Django REST framework 的工具,能够自动生成 Swagger 和 OpenAPI 格式的 API 文档。

步骤 1:安装 drf-yasg

在项目的虚拟环境中,使用以下命令安装 drf-yasg:

bash 复制代码
pip install drf-yasg
步骤 2:配置 drf-yasg

在 settings.py 文件里,把 drf_yasg 添加到 INSTALLED_APPS 列表中:

python 复制代码
INSTALLED_APPS = [
    # ...
    'drf_yasg',
    # ...
]
步骤 3:配置 URL

在项目的 urls.py 文件中添加以下代码:

python 复制代码
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="Your API",
        default_version='v1',
        description="API description",
        terms_of_service="https://www.example.com/terms/",
        contact=openapi.Contact(email="contact@example.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    # ...
    path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
    # ...
]
步骤 4:访问和导出文档
  • 访问文档界面 :启动 Django 开发服务器后,访问 http://127.0.0.1:8000/swagger/ 可查看 Swagger UI 界面,访问 http://127.0.0.1:8000/redoc/ 可查看 ReDoc 界面。
  • 导出文档 :访问 http://127.0.0.1:8000/swagger.json 或者 http://127.0.0.1:8000/swagger.yaml 就能获取 JSON 或者 YAML 格式的 OpenAPI 规范文件,可将其保存下来。

使用 django-rest-swagger 导出 Swagger 格式文档

django-rest-swagger 是较早用于 Django REST framework 的 Swagger 文档生成工具,不过该项目目前已不再维护。

步骤 1:安装 django-rest-swagger
bash 复制代码
pip install django-rest-swagger
步骤 2:配置 django-rest-swagger

在 settings.py 文件中,把 rest_framework_swagger 添加到 INSTALLED_APPS 列表中:

python 复制代码
INSTALLED_APPS = [
    # ...
    'rest_framework_swagger',
    # ...
]
步骤 3:配置 URL

在项目的 urls.py 文件中添加以下代码:

python 复制代码
from rest_framework_swagger.views import get_swagger_view

schema_view = get_swagger_view(title='Your API')

urlpatterns = [
    # ...
    path('swagger/', schema_view),
    # ...
]
步骤 4:访问和导出文档
  • 访问文档界面 :启动 Django 开发服务器后,访问 http://127.0.0.1:8000/swagger/ 可查看 Swagger UI 界面。
  • 导出文档:在 Swagger UI 界面里,点击右上角的"Export"按钮,即可导出 JSON 格式的 Swagger 文档。

使用 Spectacular 导出 OpenAPI 格式文档

drf-spectacular 是一个现代的 Django REST framework 库,可用于生成 OpenAPI 3.0 规范的 API 文档。

步骤 1:安装 drf-spectacular
bash 复制代码
pip install drf-spectacular
步骤 2:配置 drf-spectacular

在 settings.py 文件中,把 drf_spectacular 添加到 INSTALLED_APPS 列表中,并配置 REST framework:

python 复制代码
INSTALLED_APPS = [
    # ...
    'drf_spectacular',
    # ...
]

REST_FRAMEWORK = {
    # ...
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}
步骤 3:配置 URL

在项目的 urls.py 文件中添加以下代码:

python 复制代码
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    # ...
    path('schema/', SpectacularAPIView.as_view(), name='schema'),
    path('schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    # ...
]
步骤 4:访问和导出文档
  • 访问文档界面 :启动 Django 开发服务器后,访问 http://127.0.0.1:8000/schema/swagger-ui/ 可查看 Swagger UI 界面。
  • 导出文档 :访问 http://127.0.0.1:8000/schema/ 可获取 JSON 格式的 OpenAPI 规范文件,将其保存即可。
相关推荐
吃我一窝jio34 分钟前
Python与Go线程模型深度对比
java·开发语言·python
zwd20051 小时前
Manim 怎么放大画面的某一部分?
python·动画·可视化·manim·数学动画
屿华AI2 小时前
AUTOSAR 实战-诊断工具 | UDS 0x27 安全访问的配置化实现:种子密钥算法插件化设计
python·测试工具·汽车
RobinDevNotes2 小时前
Claude Code 剪视频,不上传、不要 API Key
人工智能·python·音视频·开发工具·ipython
如夏倾城4 小时前
VRRP(虚拟路由器冗余协议Virtual Router Redundancy Protocol)
网络·python·网络协议·安全·智能路由器·负载均衡·信息与通信
IvanCodes4 小时前
LangChain(04):Runnable 与 LCEL 的执行与组合机制
python·langchain·agent
特创数字科技4 小时前
纯本地离线运行的文档脱敏工具(技术分享)
前端·驱动开发·python
东莞市云毅网络有限公司6 小时前
用 Playwright 搭一套问答平台引用监测的最小骨架
python·数据清洗·rag·企业知识库·文档解析
Thanks_ks6 小时前
【第 010 讲】全面掌握 Python 变量与常量:变量的定义与赋值 | 标识符与命名规范 | 变量的底层机制 | 常量与魔术数字
python·内存·变量·标识符·常量·赋值·命名规范
飞Link6 小时前
灵巧手是什么?从机械结构、驱动方式到控制原理,认识机器人的精细操作能力
人工智能·python·机器人