API 参考

Core

class django_oasis.core.OpenAPI(*, title='API Document', name=None, description='')

参数:

• name (t.Optional[str]) – 如果需要对外分享 OAS 数据，建议设置该名称，它将作为 OAS 数据地址的一部分，而不是使用计算出的名称。

• title (str)

• description (t.Union[str, t.Callable[[HttpRequest], str]])

add_resources(module, **kwargs)

从模块中查找资源并添加。

class django_oasis.core.Operation(*, tags=None, summary=None, description=None, response_schema=None, deprecated=False, include_in_spec=True, auth=None, status_code=200, view_decorators=None, declare_responses=None)

参数:

• include_in_spec (bool) – 是否将当前操作解析到 OAS 中，默认为 True。

• summary (t.Optional[str]) – 用于设置 OAS 操作对象摘要。

• auth (t.Union[BaseAuth, t.Type[BaseAuth], None]) – 设置操作请求认证。

• declare_responses (t.Optional[dict]) – 声明可能的请求响应，用于构建 OAS。

• response_schema (t.Union[None, t.Type[schema.Model], t.Dict[str, schema.Schema], schema.Schema]) – 用于序列化请求操作返回值，并为 OAS 提供响应描述。

• description (t.Optional[str])

• deprecated (bool)

• status_code (int)

• view_decorators (t.Optional[list])

自 0.1 版本弃用: view_decorators 是一个设计错误的参数，勿用。

class django_oasis.core.Resource(path, *, param_schemas=None, param_styles=None, tags=None, view_decorators=None, url_name=None, include_in_spec=True, default_auth=None)

参数:

• path (str) – 资源 URL，必须以 “/” 开头。

• include_in_spec (bool) – 是否将当前资源解析到 OAS 中，默认为 True。

• default_auth (t.Union[BaseAuth, t.Type[BaseAuth], None]) – 为所属的 Operation 提供默认的 auth。

• url_name (t.Optional[str]) – 为 Django 提供 URL 命名。参考: 命名 URL 模式

• param_schemas (t.Optional[t.Dict[str, schema.Schema]])

• view_decorators (t.Optional[list])

Parameter

class django_oasis.parameter.Cookie(schema, styles=None)

用于声明请求 cookie 的整体或是一部分。

参数:

styles (dict[str, Style] | None)

class django_oasis.parameter.CookieItem(schema, style=None)

用于声明请求 cookie 的单个字段。

参数:

style (Style | None)

class django_oasis.parameter.FormData(schema, /)

用于声明表单请求的数据整体。

class django_oasis.parameter.FormItem(schema, /)

用于声明表单请求的单个字段。

class django_oasis.parameter.Header(schema, styles=None)

用于声明请求 header 的整体或是一部分。

参数:

styles (dict[str, Style] | None)

class django_oasis.parameter.HeaderItem(schema, style=None)

用于声明请求 header 的单个字段。

参数:

style (Style | None)

class django_oasis.parameter.JsonData(schema, /)

用于声明 JSON 请求的数据整体。

class django_oasis.parameter.JsonItem(schema, /)

用于声明 JSON 请求的单个字段。

class django_oasis.parameter.Query(schema, styles=None)

用于声明请求 query 的整体或是一部分。

参数:

styles (dict[str, Style] | None)

class django_oasis.parameter.QueryItem(schema, style=None)

用于声明请求 query 的单个字段。

参数:

style (Style | None)

class django_oasis.parameter.Style(style, explode)

参数:

• style (str)

• explode (bool)

explode: bool

当为 True 时，array或object类型的参数值为数组或映射的键值对的每个值生成单独的参数。对于其他类型的参数，此属性不起作用。查看详细说明

style: str

描述如何根据参数值的类型序列化参数值。查看详细说明

Pagination

class django_oasis.pagination.OffsetPagination(schema, /)

基类：Pagination

从 URL 参数中获取 offset 和 limit 进行分页。

参数:

schema (Schema | Type[Schema]) – 提供分页列表元素的数据结构。

class django_oasis.pagination.PagePagination(schema, /)

基类：Pagination

从 URL 参数中获取 page 和 page_size 进行分页。

参数:

schema (Schema | Type[Schema]) – 提供分页列表元素的数据结构。

class django_oasis.pagination.Pagination

分页器抽象基类

abstract _get_request_parameter()

定义分页所需要的请求参数，获取的参数结果将传递给 _get_response。

返回类型:

RequestParameter

abstract _get_response(queryset, reqarg)

获取响应数据。

参数:

• queryset (QuerySet) – 调用 paginate 时获取的查询集。

• reqarg – 使用 _get_request_parameter 返回对象获取到的请求实参。

abstract _get_response_schema()

设置分页响应数据结构，用于设置所在 Operation 的 response_schema。

返回类型:

Schema

paginate(queryset)

对 Django 查询集进行分页，并返回结果。

参数:

queryset (QuerySet)

Auth

class django_oasis.auth.BaseAuth

认证基类。如需自定义认证类，需继承该类，并实现其抽象方法。

abstract check_auth(request)

需自行实现该方法，用于判断请求认证是否成功。如果认证失败，需要抛出异常来停止请求的继续处理。

参数:

request – Django HttpRequest 对象。

declare_responses: Dict[int, dict]

描述认证时会产生的响应。键为 HTTP 状态码，值为 Response Object。

declare_security: dict

定义认证使用的安全方案。declare_security 的值为 Security Scheme Object。

备注

以下认证类是建立在使用 django.contrib.auth 包作为项目的用户验证系统。如果你的项目使用了自定义的用户验证，请查看 自定义认证。

class django_oasis.auth.IsAuthenticated

验证用户是否登录。

class django_oasis.auth.IsAdministrator

验证用户是否为管理员。

class django_oasis.auth.IsSuperuser

验证用户是否为超级管理员。

class django_oasis.auth.HasPermission(perm)

验证用户是否拥有某权限。内部调用 has_perm 方法。

参数:

perm (str) – 描述权限的字符串，格式是 “<app label>.<permission codename>”。

Schema

class django_oasis.schema.Any(*args, **kwargs)

class django_oasis.schema.AnyOf(*args, **kwargs)

参数:

schemas (t.List[Schema])

class django_oasis.schema.Boolean(*args, **kwargs)

class django_oasis.schema.Date(*args, **kwargs)

class django_oasis.schema.Datetime(*args, **kwargs)

class django_oasis.schema.Dict(*args, **kwargs)

参数:

• value (t.Union[Schema, t.Type[Schema], None]) – 定义值类型，默认为 Any。

• min_properties (t.Optional[int]) – 如果设置，则反序列化字典长度必须大于等于最小长度。

• max_properties (t.Optional[int]) – 如果设置，则反序列化字典长度必须小于等于最大长度。

class django_oasis.schema.File(*args, **kwargs)

class django_oasis.schema.Float(*args, **kwargs)

class django_oasis.schema.Integer(*args, **kwargs)

class django_oasis.schema.List(*args, **kwargs)

参数:

• item (t.Union[Schema, t.Type[Schema], None]) – 定义元素类型，默认为 Any。

• min_items (t.Optional[int]) – 如果设置，则反序列化列表长度必须大于等于最小长度。

• max_items (t.Optional[int]) – 如果设置，则反序列化列表长度必须小于等于最大长度。

• unique_items (bool) – 如果为 True，则反序列化的所有元素必须唯一，默认 False。

>>> from collections import namedtuple

>>> Book = namedtuple('Book', ['title', 'author'])
>>> books = [
...     Book(title='三体', author='刘慈欣'),
...     Book(title='活着', author='余华'),
... ]

>>> class BookSchema(Model):
...     title = String()
...     author = String()

>>> List(BookSchema).serialize(books)
[{'title': '三体', 'author': '刘慈欣'}, {'title': '活着', 'author': '余华'}]

class django_oasis.schema.Model(*args, **kwargs)

参数:

• required_fields (t.Union[t.Iterable[str], str, None]) – 覆盖原有的字段必需条件配置。设为空列表则所有字段为非必需，也可设为 "__all__" 指定所有字段为必需。

• unknown_fields (str) –

  该参数决定了在反序列化时如何处理未知字段。

  >>> class User(Model):
  ...     name = String()
  ...     age = Integer()
  
  >>> data = {'name': '张三', 'age': 24, 'address': '北京'}
  

  exclude (默认)

  >>> User().deserialize(data)
  {'name': '张三', 'age': 24}
  

  include

  >>> User(unknown_fields='include').deserialize(data)
  {'name': '张三', 'age': 24, 'address': '北京'}
  

  error

  >>> User(unknown_fields='error').deserialize(data)
  Traceback (most recent call last):
      ...
  django_oasis_schema.exceptions.ValidationError: [{'msgs': ['Unknown field.'], 'loc': ['address']}]
  

fields: Mapping[str, Schema] = <django_oasis_schema.schemas.FieldMapping object>

Model 的字段映射表

static from_dict(fields)

使用由字段组成的字典生成一个 Model 类。

参数:

fields (Dict[str, Schema])

返回类型:

Type[Model]

class django_oasis.schema.Password(*args, **kwargs)

class django_oasis.schema.Path(*args, **kwargs)

class django_oasis.schema.Schema(*args, **kwargs)

参数:

• attr – [ 作为字段时有效 ] 设置序列化输入和反序列化输出的字段映射名，默认等于字段名。

• alias – [ 作为字段时有效 ] 设置序列化输出和反序列化输入的字段映射名，默认等于字段名。

• read_only – [ 作为字段时有效 ] 如果为 True，则字段在反序列化时不会被使用，默认为 False。

• write_only – [ 作为字段时有效 ] 如果为 True，则字段在序列化时不会被使用，默认为 False。

• required – [ 作为字段时有效 ] 判断字段是否必需提供，默认必需。可设为 False 或提供 default 参数使其变为非必需。

• default – [ 作为字段时有效 ] 如果字段非必需，且设置了默认值，那么反序列化时如未提供该字段数据，则使用该默认值填充。该参数可设为一个无参函数，默认值将使用该函数的结果。

• erase – [ 作为字段时有效 ] 提供一个在反序列化时使用的函数，接受反序列化前的字段值。如函数返回 True，则该字段值将视为未定义。默认将空字符串或仅包含空白字符的字符串视为未定义。

• nullable – 执行验证时判断数据是否为 None。默认 False，表示不可以为 None。

• description – 为 OAS 提供描述内容。

• validators –

  用于设置反序列化验证函数。

  >>> def validate(value):
  ...     if value <= 0:
  ...         raise ValidationError('不是一个正整数')
  
  >>> Integer(validators=[validate]).deserialize(-1)
  Traceback (most recent call last):
      ...
  django_oasis_schema.exceptions.ValidationError: [{'msgs': ['不是一个正整数']}]
  

copy(**kwargs)

复制一个 Schema 对象。可以修改其初始化的关键字参数。

deserialize(value)

对数据进行反序列化操作。

serialize(value)

对数据进行序列化操作。

class django_oasis.schema.String(*args, **kwargs)

参数:

• pattern (t.Union[str, re.Pattern, None]) – 如果设置，则反序列化字符串必需匹配正则表达式。

• min_length (t.Optional[int]) – 如果设置，则反序列化字符串必须大于等于最小长度。

• max_length (t.Optional[int]) – 设置设置，则反序列化字符串必须小于等于最大长度。

class django_oasis.schema.Url(*args, **kwargs)

exception django_oasis.schema.ValidationError(message=None, key=None)

参数:

message (Any)

django_oasis.schema.as_getter(field)

自定义 Model 字段序列化时的取值函数。默认是对 Mapping 取索引，对其它对象取属性名。

参数:

field (Schema | str) – 字段或字段名，将取值函数应用于该字段。

>>> from django_oasis import schema

>>> class Person(schema.Model):
...     fullname = schema.String()
...
...     @schema.as_getter(fullname)
...     def get_fullname(self, data):
...         return data['firstname'] + data['lastname']

>>> Person().serialize({'firstname': '张', 'lastname': '三'})
{'fullname': '张三'}

django_oasis.schema.as_validator(field=None, /)

挂载验证函数。它会在调用验证时，执行其验证函数。

参数:

field (Schema | str | None | Callable) – 该参数用于验证 Model 字段。当设置为字段或字段名时，会将其验证函数应用于该字段，而不是 Model 自身。