模式-Django REST框架
图式
机器可读的[模式]描述了哪些资源可以通过API获得,它们的URL是什么,它们是如何表示的,以及它们支持哪些操作。
-Heroku,[Heroku平台API的JSON模式][引用]
API模式是一个有用的工具,它允许一系列用例,包括生成参考文档或驱动可以与API交互的动态客户端库。
Django REST框架为自动生成OpenAPI模式。
生成OpenAPI架构
安装pyyaml
你需要安装pyyaml
,以便将生成的模式呈现为常用的基于YAML的OpenAPI格式。
pip install pyyaml
生成静态架构。generateschema
管理命令
如果架构是静态的,则可以使用generateschema
管理命令:
./manage.py generateschema > openapi-schema.yml
一旦以这种方式生成了模式,就可以用模式生成器无法自动推断的任何附加信息对其进行注释。
您可能希望将API模式签入版本控制中,并使用每个新版本更新它,或者从站点的静态媒体中提供API模式。
生成动态模式SchemaView
如果需要动态架构,因为外键选择取决于数据库值,例如,可以将SchemaView
它将根据需要生成和服务您的架构。
路由aSchemaView
,使用get_schema_view()
帮手。
在……里面urls.py
:
from rest_framework.schemas import get_schema_view
urlpatterns = [
# ...
# Use the `get_schema_view()` helper to add a `SchemaView` to project URLs.
# * `title` and `description` parameters are passed to `SchemaGenerator`.
# * Provide view name for use with `reverse()`.
path('openapi', get_schema_view(
title="Your Project",
description="API for all things …",
version="1.0.0"
), name='openapi-schema'),
# ...
]
get_schema_view()
这个get_schema_view()
Helper接受以下关键字参数:
title
::可用于为架构定义提供描述性标题。description
较长的描述性文本。version
API的版本。默认为0.1.0
.-
url
::可用于传递架构的规范基URL。schema_view = get_schema_view( title='Server Monitoring API', url='https://www.example.org/api/' )
-
urlconf
:表示要为其生成API架构的URL conf的导入路径的字符串。这默认为Django的值ROOT_URLCONF
背景。schema_view = get_schema_view( title='Server Monitoring API', url='https://www.example.org/api/', urlconf='myproject.urls' )
-
patterns
*限制模式内省的url模式列表。如果你只想myproject.api
要在架构中公开的URL:schema_url_Patterns=[url(r‘^api/’,包括(‘myproject.api.urls’)),]
schema_view = get_schema_view( title='Server Monitoring API', url='https://www.example.org/api/', patterns=schema_url_patterns, )
-
generator_class
*可用于指定模式生成器
类传递给SchemaView
.authentication_classes
::可用于指定将应用于架构端点的身份验证类的列表。默认为settings.DEFAULT_AUTHENTICATION_CLASSES
permission_classes
::可用于指定将应用于架构端点的权限类列表。默认为settings.DEFAULT_PERMISSION_CLASSES
.renderer_classes
::可用于传递一组呈现器类,这些类可用于呈现API根端点。
自定义模式生成
您可以在整个架构级别自定义架构生成,也可以在每个视图的基础上自定义架构生成。
模式级定制
,以便自定义顶级模式子类。rest_framework.schemas.openapi.SchemaGenerator
并将其作为参数提供给generateschema
命令或get_schema_view()
辅助函数
模式生成器
一个类,它遍历一个路由URL模式列表,请求每个视图的模式,并整理得到的OpenAPI模式。
通常您将实例化模式生成器
带着title
像这样的论点:
generator = SchemaGenerator(title='Stock Prices API')
论点:
-
title
所需API的名称。 -
description
较长的描述性文本。 -
version
API的版本。默认为0.1.0
. -
url
:API模式的根URL。除非架构包含在路径前缀下,否则不需要此选项。 -
patterns
:生成架构时要检查的URL列表。默认为项目的URLConf。 -
urlconf
:生成架构时要使用的URL conf模块名。默认为settings.ROOT_URLCONF
.
get_schema(Self,Request)
返回表示OpenAPI架构的字典:
generator = SchemaGenerator(title='Stock Prices API')
schema = generator.get_schema()
这个request
参数是可选的,如果要对生成的架构应用每个用户的权限,则可以使用该参数。
如果您想要自定义生成的字典,例如添加自定义,这是一个很好的重写点。规范扩展.
按视图定制
默认情况下,视图内省由AutoSchema
实例可通过schema
属性APIView
...这提供了适当的开放API操作对象对于视图,请求方法和路径:
auto_schema = view.schema
operation = auto_schema.get_operation(...)
在编译模式时,模式生成器
打电话view.schema.get_operation()
对于每个视图、允许的方法和路径。
注*基本APIView
子类,默认内省本质上仅限于URL kwarg路径参数。为GenericAPIView
子类,包括所有提供的基于类的视图,AutoSchema
将尝试内省序列化、分页和筛选字段,并提供更丰富的路径字段描述。(这里的关键钩子是相关的GenericAPIView
属性和方法:get_serializer
, pagination_class
, filter_backends
等等)
为了自定义操作生成,您应该提供一个AutoSchema
子类、覆盖get_operation()
如你所需:
from rest_framework.views import APIView
from rest_framework.schemas.openapi import AutoSchema
class CustomSchema(AutoSchema):
def get_link(...):
# Implement custom introspection here (or in other sub-methods)
class CustomView(APIView):
"""APIView subclass with custom schema introspection."""
schema = CustomSchema()
这提供了对视图内省的完全控制。
通过设置,可以禁用视图的架构生成。schema
到None
:
class CustomView(APIView):
...
schema = None # Will not appear in schema
这也适用于以下方面的额外操作:ViewSet
s:
class CustomViewSet(viewsets.ModelViewSet):
@action(detail=True, schema=None)
def extra_action(self, request, pk=None):
...
如果你想提供一个基地AutoSchema
要在整个项目中使用的子类,您可以调整settings.DEFAULT_SCHEMA_CLASS
恰到好处。