20. API概览 Schemas

能被机器所理解的概要, 描述了通过api可得到的资源, URL, 表示方式以及支持的操作.

API概要在很多使用场景下都是有用的工具, 例如生成参考文档, 或者驱动可以与API交互的动态客户端库.

rest-framework支持自动生成OPENAPI文档.

生成API概览

安装CoreAPI和PyYAML

安装coreapi包来为REST框架提供概要支持, 同时还可能需要pyyaml包以将概要渲染为通用的YAML格式的开放API格式.

1	pip install coreapi pyyaml

两种方法来生成API描述文档:

使用generateschema管理命令生成静态的概要文件
使用SchemaView视图来生成动态的概要响应.

使用`generateschema`管理命令生成静态的概要文件

1	python manage.py generateschema > shcema.yml

之后会生成一个包含api概要的YAML语法的文件schema.yml, 之后你可以在其中添加额外信息以补充概要生成器所未能包含的其他信息.

这种方法需要手动登记版本控制信息, 并在每个新版本发布时更新该文档, 或者将其作为静态媒体文件由服务器返回.

添加动态生成概要的视图函数

在某些情况下需要的是一个动态的api概要, 因为外键的可选项可能随着数据库中的值而变动. 使用SchemaView并将其注册至路由中, 这样就可以按需生成概要.

将SchemaView添加至路由, 需要使用get_schema_view()辅助函数.

from rest_framework.schemas import get_schema_view

urlpatterns = [

    path('openapi', get_schema_view(
        title="Your Project", 
        description="API for all things …", 
        version="1.0.0"
    ), name='openapi-schema'), 
    # ...
]

参数:

title 用以提供的概要标题
description 较长的描述性文本
version 标注的api版本, 默认为0.1.0
url 可用于标注baseURL
urlconf 该概要所想要包含的urlconf的所在路径, 默认为django的ROOT_URLCONF设置项
gengerator_class 可能用以指定一个要被SchemaView所使用的SchemaGenerator的子类
authentication_classes 指定用以进行身份认证的类列表, 默认为django的DEFAULT_AUTHENTICATION_CLASSES设置项
permission_classes 指定用以进行权限验证的类列表, 默认为django的DEFAULT_PERMISSION_CLASSES设置项
renderer_classes 用以指定生成最终结果的渲染器类

示例:

schema_view = get_schema_view(
    title='Server Monitoring API', 
    url='https://www.example.org/api/', 
    urlconf='myproject.urls'
)

自定义概要生成

自定义全部API概要, 或指定视图级的自定义概要.

概要级别的自定义

如果要自定义最高级的概要, 需要子类化rest_framework.schemas.openapi.SchemaGenerator, 并将其作为参数提供给大专栏 20. API概览 Schemasde>generateschema命令或者get_schema_view辅助函数.

SchemaGenerator是一个用来遍历一个urlpattern列表, 并为其中每一个视图生成相关概要的类.

通常需要提供一个title参数将其实例化:

1	generator = SchemaGenerator(title='Stock Prices API')

可用的参数包括

title
description
version
url
patterns
urlconf

各参数的含义与在get_schema_view()函数中相同, 不再赘述. 其中只有title是必要参数.

需要重写的方法为get_schema(self, request)

该方法返回一个字典, 所包含的数据用于表示API概要.

1 2	generator = SchemaGenerator(title='Stock Prices API') schema = generator.get_schema()

request参数是可选的, 如果要对生成的模式生成应用每个用户权限, 则可以使用request参数.

如果要自定义生成的字典(例如添加自定义规范扩展名), 则可以覆盖该方法.

视图级别的自定义

默认情况下, 视图自省可通过APIView上的schema属性访问的AutoSchema实例执行. 这为视图, 请求方法和路径提供了适当的Open API操作对象:

1 2	auto_schema = view.schema operation = auto_schema.get_operation(...)

在编译概要时, SchemaGenerator为每个视图, 允许的方法和路径调用view.schema.get_operation().

注意：对于基本的APIView子类, 默认自省本质上仅限于URL关键字路径参数, 对于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 (AutoSchema):
    def get_link(...):
        # Implement custom introspection here (or in other sub-methods)

class CustomView(APIView):
    """APIView subclass with custom schema introspection."""
    schema = CustomSchema()

这为视图的自省提供了完全控制.

如果想要某个视图不被包含在api概要中, 将其schema属性设为None即可.

1
2
3

class CustomView(APIView):
    ...
    schema = None  # 不会在概要中出现该视图.

或是不想让某个ViewSet中自定义路由包含在API概要中

class CustomViewSet(viewsets.ModelViewSet):

    def extra_action(self, request, pk=None):
        ...

如果要指定某个AutoSchema的子类应用于全局, 通过DEFAULT_SCHEMA_CLASS设置项进行设置.