Schemas - Django REST framework

模式-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较长的描述性文本。

• versionAPI的版本。默认为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较长的描述性文本。
• versionAPI的版本。默认为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

这也适用于以下方面的额外操作：ViewSets：

class CustomViewSet(viewsets.ModelViewSet):

    @action(detail=True, schema=None)
    def extra_action(self, request, pk=None):
        ...

如果你想提供一个基地AutoSchema要在整个项目中使用的子类，您可以调整settings.DEFAULT_SCHEMA_CLASS恰到好处。