Django-restframework29 Schemas（概要，模式，架构）

一份机器可读的关于API接口中有哪些资源可以使用，它们的url是多少，它们是如何呈现的，以及它们支持什么操作

API架构是一种有用的工具，它允许使用实例，包括生成参考文档，或者驱动动态客户端库，这些库可以与您的API交互。

一、内部陈述架构

1. 简介
   REST框架使用核心API来在独立表单中对架构信息进行建模。然后可以将这些信息渲染为各种不同的概要格式，或者用于生成API文档。
   在使用Core API时，架构信息被表示为一个文档，它是关于API信息的顶级容器对象。可用的API交互是使用Link来表示的。每个链接都包含一个URL、HTTP方法，并且可能包含一个Field列表，该列表描述了API端点可以接受的任何参数。Link和Field 实例也可能包括描述，这些描述允许将API架构呈现给用户文档。

coreapi.Document(    title='Flight Search API',    url='https://api.example.org/',    content={        'search': coreapi.Link(            url='/search/',            action='get',            fields=[                coreapi.Field(                    name='from',                    required=True,                    location='query',                    description='City name or airport code.'                ),                coreapi.Field(                    name='to',                    required=True,                    location='query',                    description='City name or airport code.'                ),                coreapi.Field(                    name='date',                    required=True,                    location='query',                    description='Flight date in "YYYY-MM-DD" format.'                )            ],            description='Return flight availability and prices.'        )    })

1. 架构输出格式
   为了将其表现为一个HTTP响应对象，架构的内部表示必须渲染成真实的字节以供响应对象使用。
   Core JSON被设计成使用 Core API的标准格式。REST框架包含一个渲染类用于处理这种媒体类型，renderers.CoreJSONRenderer。
   其他的架构模式，如Open API (“Swagger”), JSON HyperSchema, or API Blueprint也能通过自定义渲染类来实现渲染。

2. 架构和超链接媒体
   值得指出的是，Core API还可以用于hypermedia response，这是API模式的另一种交互风格。
   使用一个API架构，整个可用的接口将作为一个端点预先呈现。对于单个API端点的响应通常以纯数据的方式呈现，而不需要在每个响应中包含任何进一步的交互。
   使用Hypermedia时，客户端会呈现一个包含数据和可用交互的文档。每个交互都将产生一个新文档，详细描述当前状态和可用的交互。

二、添加一个模式

REST框架包含一个功能自动生成一个schema，或者允许你指定一个。有许多不同的方式来为你添加一个schema。

1. 使用get_schema_view()方法

from rest_framework.schemas import get_schema_viewschema_view = get_schema_view(title="Server Monitoring API")urlpatterns = [    url('^$', schema_view),    ...]

一旦添加了视图，您就可以创建API请求来检索自动生成的模式定义。

$ http http://127.0.0.1:8000/ Accept:application/coreapi+jsonHTTP/1.0 200 OKAllow: GET, HEAD, OPTIONSContent-Type: application/vnd.coreapi+json{    "_meta": {        "title": "Server Monitoring API"    },    "_type": "document",    ...}

2. get_schema_view()的参数为：

• title：描述模式标题
• 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')

• renderer_classes：用来传递API根端点的渲染器类。

from rest_framework.schemas import get_schema_viewfrom rest_framework.renderers import CoreJSONRendererfrom my_custom_package import APIBlueprintRendererschema_view = get_schema_view(    title='Server Monitoring API',    url='https://www.example.org/api/',    renderer_classes=[CoreJSONRenderer, APIBlueprintRenderer])

• patterns
  用于限制内联的url列表，如果你仅想暴露myproject.api的urls:

schema_url_patterns = [    url(r'^api/', include('myproject.api.urls')),]schema_view = get_schema_view(    title='Server Monitoring API',    url='https://www.example.org/api/',    patterns=schema_url_patterns,)

• generator_class
  指定一个SchemaGenerator子类，用于传递SchemaView

3. 显示指定一个SchemaView

如果需要比get_schema_view()更多的控制权限，你需要使用SchemaGenerator类自动创建Document的实例，然后从视图中返回。
这个选项给您提供了您想要的任何行为灵活设置模式端点。例如，您可以将不同的权限、节流或身份验证策略应用到模式端点。

# views.pyfrom rest_framework.decorators import api_view, renderer_classesfrom rest_framework import renderers, response, schemasgenerator = schemas.SchemaGenerator(title='Bookings API')@api_view()@renderer_classes([renderers.CoreJSONRenderer])def schema_view(request):    schema = generator.get_schema(request)    return response.Response(schema)# urls.pyurlpatterns = [    url('/', schema_view),    ...]

您还可以为不同的用户提供不同的模式，这取决于他们所拥有的权限。此方法可用于确保未经身份验证的请求与经过身份验证的请求不同，或确保不同的用户根据角色的不同判断用户是否可见。

@api_view()@renderer_classes([renderers.CoreJSONRenderer])def schema_view(request):    generator = schemas.SchemaGenerator(title='Bookings API')    return response.Response(generator.get_schema(request=request))

3. 显示模式定义

自动生成方法的另一种选择是显式地指定API模式，方法是在代码中声明一个Document对象。这样做需要更多的工作，但是可以确保您对模式表示有完全的控制。

import coreapifrom rest_framework.decorators import api_view, renderer_classesfrom rest_framework import renderers, responseschema = coreapi.Document(    title='Bookings API',    content={        ...    })@api_view()@renderer_classes([renderers.CoreJSONRenderer])def schema_view(request):    return response.Response(schema)

4. 静态模式文件

最后一个选项是将您的API模式编写为静态文件，使用可用的一种格式，比如Core JSON或Open API。