在 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="[email protected]"),
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 规范文件,将其保存即可。