介紹
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] = None,
parameters: Optional[List[Union[OpenApiParameter, _SerializerType]]] = None,
request: Any = empty,
responses: Any = empty,
auth: Optional[List[str]] = None,
description: Optional[str] = None,
summary: Optional[str] = None,
deprecated: Optional[bool] = None,
tags: Optional[List[str]] = None,
exclude: bool = False,
operation: Optional[Dict] = None,
methods: Optional[List[str]] = None,
versions: Optional[List[str]] = None,
examples: Optional[List[OpenApiExample]] = None,
extensions: Optional[Dict[str, Any]] = None,
) -> Callable[[F], F]:
"""
Decorator mainly for the "view" method kind. Partially or completely overrides
what would be otherwise generated by drf-spectacular.
:param operation_id: replaces the auto-generated operation_id. make sure there
are no naming collisions.
:param parameters: list of additional or replacement parameters added to the
auto-discovered fields.
:param responses: replaces the discovered Serializer. Takes a variety of
inputs that can be used individually or combined
- ``Serializer`` class
- ``Serializer`` instance (e.g. ``Serializer(many=True)`` for listings)
- basic types or instances of ``OpenApiTypes``
- :class:`.OpenApiResponse` for bundling any of the other choices together with
either a dedicated response description and/or examples.
- :class:`.PolymorphicProxySerializer` for signaling that
the operation may yield data from different serializers depending
on the circumstances.
- ``dict`` with status codes as keys and one of the above as values.
Additionally in this case, it is also possible to provide a raw schema dict
as value.
- ``dict`` with tuples (status_code, media_type) as keys and one of the above
as values. Additionally in this case, it is also possible to provide a raw
schema dict as value.
:param request: replaces the discovered ``Serializer``. Takes a variety of inputs
- ``Serializer`` class/instance
- basic types or instances of ``OpenApiTypes``
- :class:`.PolymorphicProxySerializer` for signaling that the operation
accepts a set of different types of objects.
- ``dict`` with media_type as keys and one of the above as values. Additionally in
this case, it is also possible to provide a raw schema dict as value.
:param auth: replace discovered auth with explicit list of auth methods
:param description: replaces discovered doc strings
:param summary: an optional short summary of the description
:param deprecated: mark operation as deprecated
:param tags: override default list of tags
:param exclude: set True to exclude operation from schema
:param operation: manually override what auto-discovery would generate. you must
provide a OpenAPI3-compliant dictionary that gets directly translated to YAML.
:param methods: scope extend_schema to specific methods. matches all by default.
:param versions: scope extend_schema to specific API version. matches all by default.
:param examples: attach request/response examples to the operation
:param extensions: specification extensions, e.g. ``x-badges``, ``x-code-samples``, etc.
:return:
"""
if methods is not None:
methods = [method.upper() for method in methods]
def decorator(f):
BaseSchema = (
# explicit manually set schema or previous view annotation
getattr(f, 'schema', None)
# previously set schema with @extend_schema on views methods
or getattr(f, 'kwargs', {}).get('schema', None)
# previously set schema with @extend_schema on @api_view
or getattr(getattr(f, 'cls', None), 'kwargs', {}).get('schema', None)
# the default
or api_settings.DEFAULT_SCHEMA_CLASS
)
if not inspect.isclass(BaseSchema):
BaseSchema = BaseSchema.__class__
def is_in_scope(ext_schema):
version, _ = ext_schema.view.determine_version(
ext_schema.view.request,
**ext_schema.view.kwargs
)
version_scope = versions is None or version in versions
method_scope = methods is None or ext_schema.method in methods
return method_scope and version_scope
class ExtendedSchema(BaseSchema):
def get_operation(self, path, path_regex, path_prefix, method, registry):
self.method = method.upper()
if exclude and is_in_scope(self):
return None
if operation is not None and is_in_scope(self):
return operation
return super().get_operation(path, path_regex, path_prefix, method, registry)
def get_operation_id(self):
if operation_id and is_in_scope(self):
return operation_id
return super().get_operation_id()
def get_override_parameters(self):
if parameters and is_in_scope(self):
return super().get_override_parameters() + parameters
return super().get_override_parameters()
def get_auth(self):
if auth and is_in_scope(self):
return auth
return super().get_auth()
def get_examples(self):
if examples and is_in_scope(self):
return super().get_examples() + examples
return super().get_examples()
def get_request_serializer(self):
if request is not empty and is_in_scope(self):
return request
return super().get_request_serializer()
def get_response_serializers(self):
if responses is not empty and is_in_scope(self):
return responses
return super().get_response_serializers()
def get_description(self):
if description and is_in_scope(self):
return description
return super().get_description()
def get_summary(self):
if summary and is_in_scope(self):
return str(summary)
return super().get_summary()
def is_deprecated(self):
if deprecated and is_in_scope(self):
return deprecated
return super().is_deprecated()
def get_tags(self):
if tags is not None and is_in_scope(self):
return tags
return super().get_tags()
def get_extensions(self):
if extensions and is_in_scope(self):
return extensions
return super().get_extensions()
if inspect.isclass(f):
# either direct decoration of views, or unpacked @api_view from OpenApiViewExtension
if operation_id is not None or operation is not None:
error(
f'using @extend_schema on viewset class {f.__name__} with parameters '
f'operation_id or operation will most likely result in a broken schema.'
)
# reorder schema class MRO so that view method annotation takes precedence
# over view class annotation. only relevant if there is a method annotation
for view_method_name in get_view_method_names(view=f, schema=BaseSchema):
if 'schema' not in getattr(getattr(f, view_method_name), 'kwargs', {}):
continue
view_method = isolate_view_method(f, view_method_name)
view_method.kwargs['schema'] = type(
'ExtendedMetaSchema', (view_method.kwargs['schema'], ExtendedSchema), {}
)
# persist schema on class to provide annotation to derived view methods.
# the second purpose is to serve as base for view multi-annotation
f.schema = ExtendedSchema()
return f
elif callable(f) and hasattr(f, 'cls'):
# 'cls' attr signals that as_view() was called, which only applies to @api_view.
# keep a "unused" schema reference at root level for multi annotation convenience.
setattr(f.cls, 'kwargs', {'schema': ExtendedSchema})
# set schema on method kwargs context to emulate regular view behaviour.
for method in f.cls.http_method_names:
setattr(getattr(f.cls, method), 'kwargs', {'schema': ExtendedSchema})
return f
elif callable(f):
# custom actions have kwargs in their context, others don't. create it so our create_view
# implementation can overwrite the default schema
if not hasattr(f, 'kwargs'):
f.kwargs = {}
# this simulates what @action is actually doing. somewhere along the line in this process
# the schema is picked up from kwargs and used. it's involved my dear friends.
# use class instead of instance due to descriptor weakref reverse collisions
f.kwargs['schema'] = ExtendedSchema
return f
else:
return f
return decorator
這個裝飾器主要用於view，通過drf-spectacular部分或完全的覆蓋去產生些東西
先來看下幾個初始化引數
- operation_id：一個唯一標識ID，基本用不到
- parameters：新增到列表中的附加或替換引數去自動發現欄位。
- responses：替換
Serializer。需要各種各樣的可單獨使用或組合使用的輸入(有以下7種)Serializer類- 序列化例項，比如：
Serializer(many=True) OpenApiTypes的基本型別或者例項OpenApiResponse類PolymorphicProxySerializer類- 1個字典，以狀態碼作為鍵， 以上其中一項作為值(是最常用的，格式
{200, None}) - 1個字典，以狀態碼作為鍵，以
media_type作為值
- request：替換序列化，接受各種輸入
Serializer類或者例項OpenApiTypes基本型別或者例項PolymorphicProxySerializer類- 1個字典，以
media_type作為鍵，以上其中一項作為值
- auth：用auth方法的顯式列表替換發現的auth
- description：替換發現的文件字串
- summary：一個可選的短的總結描述
- deprecated：將操作標記為已棄用
- tags：覆蓋預設標記列表
- exclude：設定為True以從
schema中排除操作 - operation：手動覆蓋自動發現將生成的內容。你必須提供一個相容
OpenAPI3的字典，該字典可以直接翻譯成YAML。 - methods：檢查
extend_schema中特殊的方法，預設匹配所有 - versions：檢查
extend_schema中特殊的API版本，預設匹配所有 - example：將請求/響應示例附加到操作中
- extensions：規範擴充套件