Django（74）drf-spectacular自动生成接口文档

介绍

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] =