介绍
drf-spectacular
是为Django REST Framework
生成合理灵活的OpenAPI 3.0
模式。它可以自动帮我们提取接口中的信息,从而形成接口文档,而且内容十分详细,再也不用为写接口文档而心烦了
这个库主要实现了3个目标
- 从DRF中提取更多的schema信息
- 提供灵活性,使schema在现实世界中可用(不仅仅是示例)
- 生成一个与最流行的客户端生成器配合良好的schema
环境准备
- Python >= 3.6
- Django (2.2, 3.1, 3.2)
- Django REST Framework (3.10, 3.11, 3.12)
安装
使用pip
命令安装
pip install drf-spectacular
然后在settings.py
的INSTALLED_APPS
安装drf-spectacular
INSTALLED_APPS = [
# ALL YOUR APPS
'drf_spectacular',
]
最后向DRF注册我们壮观的AutoSchema
REST_FRAMEWORK = {
# YOUR SETTINGS
'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}
drf-spectacular
有健全的默认设置,非常好用开箱即用,不需要指定任何设置,但我们建议至少指定一些元数据
SPECTACULAR_SETTINGS = {
'TITLE': 'API接口文档',
'DESCRIPTION': '项目详情介绍',
'VERSION': '1.0.0',
# OTHER SETTINGS
}
使用方式
我们只需要在urls.py
中添加接口地址即可
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView
urlpatterns = [
# YOUR PATTERNS
path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
# Optional UI:
path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'), # swagger接口文档
path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'), # redoc接口文档
]
然后我们启动项目,访问http://127.0.0.1:8000/api/schema/swagger-ui/
,就会出现接口文档
我们可以看到图上有我们之前在settings.py
中配置的TITLE
和DESCRIPTION
和VERSION
,如果想自定义更多的设置,请看文档
自定义接口内容信息
上面我们可以访问swagger
接口文档,但是我们点开接口会发现没有任何内容信息
所以我们还需要在view
视图中,使用装饰器@extend_schema
来制定接口文档中的接口信息
我们先来看下装饰器extend_schema
的源码
def extend_schema(
operation_id: Optional[str] =