查询参数 (Query)¶

声明和获取查询参数需要使用 django_oasis.parameter.Query，它的使用方法如下:

views.py [示例1]¶

from django_oasis import schema
from django_oasis.core import Resource
from django_oasis.parameter import Query


# 定义所需的参数结构
# 这里定义了 2 个参数 a, b
class QuerySchema(schema.Model):
    a = schema.String()
    b = schema.Integer()


@Resource("/to/path")
class API:
    def get(
        self,
        query=Query(QuerySchema),  # 以关键字参数的形式设置在请求操作函数中
    ): ...

如示例所见，查询参数的声明由2部分组成:

QuerySchema 是一个 Schema 类，它用于定义请求参数名、数据类型等，并且为实际的请求参数执行反序列化及验证。有关 Schema 的详细说明请查看相应章节。
Query 用于声明请求参数位于 “查询参数” 中。

最终 get 方法获取的 query 参数值为 QuerySchema 对请求参数反序列化后得到的值。

在此示例中，如果查询参数为 ?a=1&b=2，则 query = {"a": "1", "b": 2}。

SwaggerUI [示例1]

简洁写法¶

在声明请求参数时，可以使用字典代替 Schema，这样写起来更加简洁。如下代码等同于上面的示例。

@Resource("/to/path")
class API:
    def get(
        self,
        query=Query({
            'a': schema.String(),
            'b': schema.Integer()
        }),
    ): ...

备注

实际上，在使用字典代替 Schema 时，Query 内部调用了 Model.from_dict 方法。

分组声明¶

如果需要对参数获取进行分组处理，可以使用分组声明的方式。

views.py [示例2]¶

from django_oasis import schema
from django_oasis.core import Resource
from django_oasis.parameter import Query


@Resource("/to/path")
class API:
    def get(
        self,
        q1=Query({"a": schema.String(), "b": schema.String()}),
        q2=Query({"c": schema.String()}),
    ): ...

q1 和 q2 将查询参数拆分为了两组。

如查询参数为 ?a=1&b=2&c=3，则 q1 = {"a": "1", "b": "2"} q2 = {"c": "3"}。

SwaggerUI [示例2]

单参数项声明¶

如果仅需要对单个参数项进行声明，使用 django_oasis.parameter.QueryItem 。

views.py [示例3]¶

from django_oasis import schema
from django_oasis.core import Resource
from django_oasis.parameter import QueryItem


@Resource("/to/path")
class API:
    def get(
        self,
        a=QueryItem(schema.Integer),
        b=QueryItem(schema.Integer(default=0)),
    ): ...

备注

QueryItem 本身并不参与实际功能，它只是被转换为了 Query 的形式。所以上面代码等效于：

@Resource("/to/path")
class API:
    def get(self, query=Query({
        "a": schema.Integer(),
        "b": schema.Integer(default=0),
    })): ...

SwaggerUI [示例3]

参数样式查询表¶

数组样式¶

以下示例的参数结果示例 color = ["blue", "black", "brown"]

color=blue&color=black&color=brown (default)¶

views.py [示例4]¶

@Resource("/array/form/true")
class ArrayFormTrueAPI:
    def get(
        self,
        color=QueryItem(
            schema.List(schema.String()),
            Style("form", True),
        ),
    ):
        ...

color=blue,black,brown¶

views.py [示例4]¶

@Resource("/array/form/false")
class ArrayFormFalseAPI:
    def get(
        self,
        color=QueryItem(
            schema.List(schema.String()),
            Style("form", False),
        ),
    ):
        ...

color=blue black brown¶

views.py [示例4]¶

@Resource("/array/spaceDelimited/false")
class ArraySpaceDelimitedFalseAPI:
    def get(
        self,
        color=QueryItem(
            schema.List(schema.String()),
            Style("spaceDelimited", False),
        ),
    ):
        ...

color=blue|black|brown¶

views.py [示例4]¶

@Resource("/array/pipeDelimited/false")
class ArrayPipeDelimitedFalseAPI:
    def get(
        self,
        color=QueryItem(
            schema.List(schema.String()),
            Style("pipeDelimited", False),
        ),
    ):
        ...

对象样式¶

以下示例的参数结果示例 color = {"R": 100, "G": 200, "B": 500}

R=100&G=200&B=150 (default)¶

views.py [示例4]¶

@Resource("/object/form/true")
class ObjectFormTrueAPI:
    def get(
        self,
        color=QueryItem(
            schema.Model.from_dict(
                {
                    "R": schema.Integer(),
                    "G": schema.Integer(),
                    "B": schema.Integer(),
                }
            ),
            Style("form", True),
        ),
    ):
        ...

color=R,100,G,200,B,150¶

views.py [示例4]¶

@Resource("/object/form/false")
class ObjectFormFalseAPI:
    def get(
        self,
        color=QueryItem(
            schema.Model.from_dict(
                {
                    "R": schema.Integer(),
                    "G": schema.Integer(),
                    "B": schema.Integer(),
                }
            ),
            Style("form", False),
        ),
    ):
        ...

color[R]=100&color[G]=200&color[B]=150¶

views.py [示例4]¶

@Resource("/object/deepObject/true")
class ObjectDeepObjectTrueAPI:
    def get(
        self,
        color=QueryItem(
            schema.Model.from_dict(
                {
                    "R": schema.Integer(),
                    "G": schema.Integer(),
                    "B": schema.Integer(),
                }
            ),
            Style("deepObject", True),
        ),
    ):
        ...

SwaggerUI [示例4]