Django-restframework29 Schemas(概要,模式,架构)

版权声明:本文为博主原创文章,遵循 CC 4.0 by-sa 版权协议,转载请附上原文出处链接和本声明。
本文链接:https://blog.csdn.net/runnoob_1115/article/details/78506684

一份机器可读的关于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_view

schema_view = get_schema_view(title="Server Monitoring API")

urlpatterns = [
    url('^$', schema_view),
    ...
]

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

$ http http://127.0.0.1:8000/ Accept:application/coreapi+json
HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-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_view
from rest_framework.renderers import CoreJSONRenderer
from my_custom_package import APIBlueprintRenderer

schema_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.py
from rest_framework.decorators import api_view, renderer_classes
from rest_framework import renderers, response, schemas

generator = 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.py
urlpatterns = [
    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 coreapi
from rest_framework.decorators import api_view, renderer_classes
from rest_framework import renderers, response

schema = 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。

展开阅读全文

没有更多推荐了,返回首页