介绍

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, SpectacularSwaggerViewurlpatterns = [# YOUR PATTERNSpath(\'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 overrideswhat would be otherwise generated by drf-spectacular.:param operation_id: replaces the auto-generated operation_id. make sure thereare no naming collisions.:param parameters: list of additional or replacement parameters added to theauto-discovered fields.:param responses: replaces the discovered Serializer. Takes a variety ofinputs 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 witheither a dedicated response description and/or examples.- :class:`.PolymorphicProxySerializer` for signaling thatthe operation may yield data from different serializers dependingon 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 dictas value.- ``dict`` with tuples (status_code, media_type) as keys and one of the aboveas values. Additionally in this case, it is also possible to provide a rawschema 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 operationaccepts a set of different types of objects.- ``dict`` with media_type as keys and one of the above as values. Additionally inthis 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 mustprovide 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 annotationgetattr(f, \'schema\', None)# previously set schema with @extend_schema on views methodsor getattr(f, \'kwargs\', {}).get(\'schema\', None)# previously set schema with @extend_schema on @api_viewor getattr(getattr(f, \'cls\', None), \'kwargs\', {}).get(\'schema\', None)# the defaultor 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 versionsmethod_scope = methods is None or ext_schema.method in methodsreturn method_scope and version_scopeclass 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 Noneif operation is not None and is_in_scope(self):return operationreturn 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_idreturn super().get_operation_id()def get_override_parameters(self):if parameters and is_in_scope(self):return super().get_override_parameters() + parametersreturn super().get_override_parameters()def get_auth(self):if auth and is_in_scope(self):return authreturn super().get_auth()def get_examples(self):if examples and is_in_scope(self):return super().get_examples() + examplesreturn super().get_examples()def get_request_serializer(self):if request is not empty and is_in_scope(self):return requestreturn super().get_request_serializer()def get_response_serializers(self):if responses is not empty and is_in_scope(self):return responsesreturn super().get_response_serializers()def get_description(self):if description and is_in_scope(self):return descriptionreturn 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 deprecatedreturn super().is_deprecated()def get_tags(self):if tags is not None and is_in_scope(self):return tagsreturn super().get_tags()def get_extensions(self):if extensions and is_in_scope(self):return extensionsreturn super().get_extensions()if inspect.isclass(f):# either direct decoration of views, or unpacked @api_view from OpenApiViewExtensionif 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 annotationfor view_method_name in get_view_method_names(view=f, schema=BaseSchema):if \'schema\' not in getattr(getattr(f, view_method_name), \'kwargs\', {}):continueview_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-annotationf.schema = ExtendedSchema()return felif 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 felif callable(f):# custom actions have kwargs in their context, others don\'t. create it so our create_view# implementation can overwrite the default schemaif 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 collisionsf.kwargs[\'schema\'] = ExtendedSchemareturn felse:return freturn decorator

这个装饰器主要用于

view

，通过

drf-spectacular

部分或完全的覆盖去产生些东西

先来看下几个初始化参数

• operation_id：一个唯一标识ID，基本用不到
• parameters：添加到列表中的附加或替换参数去自动发现字段。
• responses：替换

  Serializer

  。需要各种各样的可单独使用或组合使用的输入(有以下7种)

  Serializer

  类

• 序列化实例，比如：

  Serializer(many=True)

• OpenApiTypes

  的基本类型或者实例

• OpenApiResponse

  类

• PolymorphicProxySerializer

  类

• 1个字典，以状态码作为键， 以上其中一项作为值(是最常用的，格式

  {200, None}

  )

• 1个字典，以状态码作为键，以

  media_type

  作为值

schema

OpenAPI3

YAML

extend_schema

extend_schema

最后我们在登录视图的post方法中添加

@extend_schema

装饰器，传入上面你所需要的字段，就可以了

@extend_schema(summary="Login",request=UserModelSerializer,responses={200: UserModelSerializer},description="登录接口",versions=["v1"])

最后我们就能看到完整的接口文档了