POSTMAN自动生成接口文档_django官方文档

POSTMAN自动生成接口文档_django官方文档介绍drf-spectacular是为DjangoRESTFramework生成合理灵活的OpenAPI3.0模式。它可以自动帮我们提取接口中的信息,从而形成接口文档,而且内容十分详细,再也不

大家好,又见面了,我是你们的朋友全栈君。如果您正在找激活码,请点击查看最新教程,关注关注公众号 “全栈程序员社区” 获取激活教程,可能之前旧版本教程已经失效.最新Idea2022.1教程亲测有效,一键激活。

Jetbrains全系列IDE使用 1年只要46元 售后保障 童叟无欺

介绍

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.pyINSTALLED_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/,就会出现接口文档
POSTMAN自动生成接口文档_django官方文档
我们可以看到图上有我们之前在settings.py中配置的TITLEDESCRIPTIONVERSION,如果想自定义更多的设置,请看文档
 

自定义接口内容信息

上面我们可以访问swagger接口文档,但是我们点开接口会发现没有任何内容信息
POSTMAN自动生成接口文档_django官方文档
所以我们还需要在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:规范扩展

最后我们在登录视图的post方法中添加@extend_schema装饰器,传入上面你所需要的字段,就可以了

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

最后我们就能看到完整的接口文档了
POSTMAN自动生成接口文档_django官方文档

版权声明:本文内容由互联网用户自发贡献,该文观点仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 举报,一经查实,本站将立刻删除。

发布者:全栈程序员-用户IM,转载请注明出处:https://javaforall.cn/165705.html原文链接:https://javaforall.cn

【正版授权,激活自己账号】: Jetbrains全家桶Ide使用,1年售后保障,每天仅需1毛

【官方授权 正版激活】: 官方授权 正版激活 支持Jetbrains家族下所有IDE 使用个人JB账号...

(0)
blank

相关推荐

  • 记一次没遇到过的UPX脱壳

    记一次没遇到过的UPX脱壳关于壳的介绍见CTF-WIKI这里就不多赘述了拿到我们的程序,先查看64位upx壳,首先直接upx-d试一下,结果是失败报错提示下图(一开始也有怀疑过是不是版本不兼容的问题,后来尝试高版本还是兼容低版本的)然后想尝试手脱,打开x64dbg,单步下去直接跑飞了,重新载入,想看看f7能否跟进,结果发现第一个指令是一个jmp指令,遂失败搜索这个报错无果,问了师傅,可能是upx非标准格式,找到了一篇文章链接如下:https://www.52pojie.cn/thread-326995-1-1.

  • 代码解读器_网页代码解读

    代码解读器_网页代码解读0写在前面在对STN的原论文进行了翻译、理解后,我打算去github上运行下源码,以加深对ST的理解。毕竟,talkischeap,showmethecode!此外,虽然论文作者发布是tf的源码,但由于我对tensorflow不如pytorch熟稔,因此这里我只看了pytorch官网复现的STN代码。发现写得非常详细,很适合小白入门,因此我放弃了自己解读的机会,打算就搬运一下原教程哈哈。1具体教程注:以下内容均为复制/翻译,不过我在代码上加了点中文注释Spatialtransfor

  • oracle杀进程命令_oracle如何查看进程

    oracle杀进程命令_oracle如何查看进程1、查看锁表进程–1.查看锁表进程SQL语句selectsess.sid,sess.serial#,lo.oracle_username,lo.os_user_name,ao.object_name,lo.locked_modefromv$locked_objectlo,dba_objectsao…

  • yum 安装卸载mysql_yum 安装卸载mysql

    yum 安装卸载mysql_yum 安装卸载mysqllinux下使用yum安装mysql1、安装查看有没有安装过:yumlistinstalledmysql*rpm-qa|grepmysql*查看有没有安装包:yumlistmysql*安装mysql客户端:yuminstallmysql安装mysql服务器端:yuminstallmysql-serveryuminstallmysql-develwww.2cto.co…

  • 怎么判断摄像头开没开_qt获取控制台输出并显示

    怎么判断摄像头开没开_qt获取控制台输出并显示一、系统环境介绍PC环境:ubuntu18.04Android版本:8.1Android设备:友善之臂RK3399开发板摄像头:罗技USB摄像头FFMPEG版本:4.2.2NDK版本:R19CQT版本:5.12二、QT代码关于FFMPEG库的编译、QT的环境搭建等问题,可以看上篇文章。直接上核心代码:#include”main…

发表回复

您的电子邮箱地址不会被公开。

关注全栈程序员社区公众号