【Django-ninja】使用schema

 在Django Ninja中，"schema"主要是指帮助描述和规范你的API的工具，以便系统能够自动生成文档并提供验证。通俗地说，它有两个主要作用：

1. API文档生成器： Schema 让 Django Ninja 能够自动生成互动式的API文档。就像一个自动化的说明书，告诉开发者每个API端点是什么，它需要什么样的输入，返回什么样的输出。这样，开发者可以通过查看这份文档更容易地理解和测试API。

2. 数据验证器： Schema 也用于验证API请求和响应中的数据。它规定了输入数据的格式和类型，以及API应该如何响应请求。这确保了API的数据是符合预期的，提高了系统的健壮性和可靠性。

总的来说，Django Ninja中的Schema就像一个帮你整理和规范API的工具，使得API的开发、使用和测试更加简单和清晰。

from ninja import NinjaAPI, Field, Schema


class AddIn(Schema):
    """推理请求输入."""
    query: str = Field(default="query")
    a: float = Field(title="参数a",
                     description="加法参数a",
                     gt=10)
    b: float = Field()


class AddResponse(Schema):
    data: dict
    code: int = Field(default=200)


class AddError(Schema):
    message: str


@api.post("/add", response={200: AddResponse, 403: AddError})
def add(request, req: AddIn):
    try:
        print(f"query: {req.query}")
        return 200, AddResponse(data=dict(result=req.a + req.b))
        # return 200, {"data": dict(result=req.a + req.b)} # 这样也是可以的。
    except:
        return 403, AddError(message="error")


@api.get("/get_add")
def get_add(request, req: AddIn = Query(...)):
    return {"data": req.a + req.b}

post方法的schema

这里如果用的是return 200, {"data": dict(result=req.a + req.b)}， 后面的字典会自动通过AddResponse类格式化处理，然后输出。

所以如果@api.post中指定了response为字典，需要注意返回值应该是一个tuple，第一值是key, 第二个值是可以通过相应的schema转化的字典数据。

get方法的schema

以下代码，我是这样理解的。所有get请求中的query参数，也就是/get_add?a=12&b=1这个请求路径中的a和b以及其他可能的参数，通通都会被Query类收集起来，然后Query类会被AddIn格式化，所以最终传递到函数体内到req是一个AddIn类型。（todo可能理解不对。我消化消化）

@api.get("/get_add")
def get_add(request, req: AddIn = Query(...)):
    return {"data": req.a + req.b}