介绍 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_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 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 freturn decorator

这个装饰器主要用于view，通过drf-spectacular部分或完全的覆盖去产生些东西
【Django（74）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：规范扩展

推荐阅读

• 

  信贷逾期能去银行开户吗知乎 信贷逾期能去银行开户吗？
• 

  英语演讲拍摄什么，英语演讲需要准备什么
• 

  sql 组内加序号 mysql组内加序号
• 

  plc按输出类型分为哪三类，写出plc常用的三种输出类型
• 

  李白、苏东坡两人,他们的共同点、不同点是什么？
• 

  硬核科技OPPO|硬核科技OPPO Reno系列4月1日正式开启预约
• 

  糖尿病|糖尿病主食怎么吃？听听3名糖尿病患者怎么说！吃饱吃好不升糖
• 

  冰箱的功能和作用：了解冰箱的各种特性及其在日常生活中的重要作用
• 

  盈余公积主要用途包括哪些 盈余公积的形成
• 

  黄桃和水蜜桃味道有什么不一样
• 

  如何制作数据图表视频教学 如何制作数据图表视频，如何制作数据图表视频教程
• 

  晚上吃水煮秋葵可以减肥吗
• 

  游戏版|红米K40游戏手机未售先崩！谁也没想到，“打脸”竟来得如此之快！
• 

  核酸结果检测中要多久可以出来
• 

  白醋洗白衣服的正确方法 白醋洗白衣服的正确步骤
• 

  可以带一小瓶花椒油上飞机吗
• 

  鼠简笔画 鼠简笔画报
• 

  redis客户端工具有哪些 redis支持客户端
• 

  甲状腺弥漫性肿大怎样治疗 甲状腺弥漫性肿大
• 

  最新版苹果ipad是哪款，哪一款ipad是最新出来的叫什么名字

• django-前后端交互
• django2.2|django2.2 一般项目步骤（初步）
• Java代码辅助效率工具Lombok(注解|Java代码辅助效率工具Lombok(注解,自动生成代码)
• django|django 自定义.save()方法
• django|django 获取用户的域名
• django开发电子商城（二十二）购物车商品的所有者身份转换
• Django安装mysql
• Django记录操作日志与LogEntry的使用详解
• 1.3Django中创建项目
• 使用django内置邮件服务