Django(74)drf-spectacular自动生成接口文档
2021-11-02 18:06
1336 查看
介绍
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
作为值
Serializer类或者实例
OpenApiTypes基本类型或者实例
PolymorphicProxySerializer类
media_type作为键,以上其中一项作为值
schema中排除操作
OpenAPI3的字典,该字典可以直接翻译成
YAML。
extend_schema中特殊的方法,默认匹配所有
extend_schema中特殊的API版本,默认匹配所有
最后我们在登录视图的post方法中添加
@extend_schema装饰器,传入上面你所需要的字段,就可以了
@extend_schema( summary="Login", request=UserModelSerializer, responses={200: UserModelSerializer}, description="登录接口", versions=["v1"] )
最后我们就能看到完整的接口文档了
相关文章推荐
- django-rest-framework 自动生成接口说明文档
- Python3+ Django3:自动生成Swagger接口文档
- python django自动生成接口文档
- app后端开发二:API接口文档自动生成工具
- Web API 自动生成接口文档
- django-rest-framework分页pagination和自动生成api文档
- 生成项目依赖包文档、自动生成接口文档
- 使用swagger根据本地接口文档自动生成mock数据
- 3.9自动生成接口文档
- weiapi2.2 HelpPage自动生成接口说明文档和接口测试功能
- springboot apidoc自动生成接口文档
- EasyDSS流媒体解决方案之接口文档自动生成
- 【Vue+DRF生鲜电商】20.使用DRF自动生成文档的功能
- Swagger自动接口文档生成框架————springboot整合swagger总结
- DRF生成接口文档时报错
- Postman接口测试(四):接口描述与自动生成文档
- weiapi2.2 HelpPage自动生成接口说明文档和接口测试功能
- weiapi2.2 HelpPage自动生成接口说明文档和接口测试功能
- [置顶] 使用spring-restdocs 自动生成接口文档
- Spring Rest Docs WebTestClient自动生成接口文档Gradle版