FastAPI后台开发基础（4）：FastAPI 官网文档错误、编码错误以及注意要点记录

@app.get("/validation")
async def async_root(str_param: Annotated[str | None, Query(min_length = 3,
                                                            max_length = 20,
                                                            pattern = '^[a-zA-Z0-9]+$',
                                                            description = 'This is a string parameter')]):
    """
    如果不设置 str_param = None, 则 str_param 为必填
    """
    ret = {"str_list": str_param}
    if str_param is not None:
        h = hashlib.sha3_512(str_param.encode('utf-8')).hexdigest()
        ret.update({"sha3_512": h})
    else:
        ret.update({"uuid": uuid.uuid4().hex})
    return ret

@app.get("/validation1")
async def async_root1(str_param: Annotated[str | None, Query(min_length = 3,
                                                             max_length = 20,
                                                             pattern = '^[a-zA-Z0-9]+$',
                                                             description = 'This is a string parameter')] = None):
    """
    设置 str_param = None 表明允许 str_param 为空(非必填)
    """
    ret = {"str_list": str_param}
    if str_param is not None:
        h = hashlib.sha3_512(str_param.encode('utf-8')).hexdigest()
        ret.update({"sha3_512": h})
    else:
        ret.update({"uuid": uuid.uuid4().hex})
    return ret

@app.get("/validation2")
async def async_root2(str_param: Annotated[str, Query(min_length = 3,
                                                      max_length = 20,
                                                      pattern = '^[a-zA-Z0-9]+$',
                                                      description = 'This is a string parameter')] = 'default_value'):
    """
    此时 str_list 有默认值，非必填
    """
    ret = {"str_list": str_param}
    if str_param is not None:
        h = hashlib.sha3_512(str_param.encode('utf-8')).hexdigest()
        ret.update({"sha3_512": h})
    else:
        ret.update({"uuid": uuid.uuid4().hex})
    return ret

@app.get("/validation3")
async def async_root3(str_param: Annotated[str, Query(min_length = 3,
                                                      max_length = 20,
                                                      pattern = '^[a-zA-Z0-9]+$',
                                                      description = 'This is a string parameter')] = ...):
    """
    此时 str_list = ... 生成的文档中，str_list 并非为必填
    并且当发送请求：
        curl -X 'GET' 'http://127.0.0.1:18081/validation3' -H 'accept: application/json'
    后台会报错：
        ValueError: [TypeError("'ellipsis' object is not iterable"), TypeError('vars() argument must have __dict__ attribute')]
    """
    ret = {}
    if str_param is not ...:
        ret = {"str_list": str_param}
        h = hashlib.sha3_512(str_param.encode('utf-8')).hexdigest()
        ret.update({"sha3_512": h})
    else:
        ret.update({"uuid": uuid.uuid4().hex, 'error': 'str_list is ...'})
    return ret


@app.get("/validation4")
async def async_root4(str_param: Annotated[str | None, Query(min_length = 3,
                                                             max_length = 20,
                                                             pattern = '^[a-zA-Z0-9]+$',
                                                             description = 'This is a string parameter')] = ...):
    """
    发送：curl -X 'GET' 'http://127.0.0.1:18081/validation4' -H 'accept: application/json'时
    后台会报错：ValueError: [TypeError("'ellipsis' object is not iterable"), TypeError('vars() argument must have __dict__ attribute')]
    """
    ret = {}
    if str_param is not ...:
        ret = {"str_list": str_param}
        h = hashlib.sha3_512(str_param.encode('utf-8')).hexdigest()
        ret.update({"sha3_512": h})
    else:
        ret.update({"uuid": uuid.uuid4().hex, 'error': 'str_list is ...'})
    return ret

@app.get("/validation5")
async def async_root5(str_param: Annotated[str, Query(default = ...,
                                                      min_length = 3,
                                                      max_length = 20,
                                                      pattern = '^[a-zA-Z0-9]+$',
                                                      description = 'This is a string parameter')]):
    """
    使用 Query(default = ...) 的方式设置 str_list 为必填参数
    不使用 default 时参数也会默认为必填
    Remember that in most of the cases, when something is required,
    you can simply omit the default, so you normally don't have to use ...
    """
    ret = {"str_list": str_param}
    h = hashlib.sha3_512(str_param.encode('utf-8')).hexdigest()
    ret.update({"sha3_512": h})
    ret.update({"uuid": uuid.uuid4().hex})
    return ret

@app.get("/validation1_1")
async def async_root1_1(str_param: Annotated[str | None, Query(default = 'test',
                                                               min_length = 3,
                                                               max_length = 20,
                                                               pattern = '^[a-zA-Z0-9]+$',
                                                               description = 'This is a string parameter')]):
    ret = {"str_list": str_param}
    if str_param is not None:
        h = hashlib.sha3_512(str_param.encode('utf-8')).hexdigest()
        ret.update({"sha3_512": h})
    else:
        ret.update({"uuid": uuid.uuid4().hex})
    return ret

AssertionError: `Query` default value cannot be set in `Annotated` for 'str_param'. Set the default value with `=` instead.

@app.get("/validation7")
async def async_root7(str_list: Annotated[List[str] | None, Query(min_length = 1)]):
    """
    列表查询参数
    curl -X 'GET' 'http://127.0.0.1:18081/validation7?str_list=aaa&str_list=bbb&str_list=ccc' -H 'accept: application/json'
    """
    if str_list is not None:
        return {'items_count': len(str_list), 'items': str_list}
    else:
        return {'message': 'no items'}

@app.get('/{item_id}')
async def async_root(item_id: Annotated[int, Path(title = 'Item ID', alias = 'xid')]):
    """
    GithubIssue: https://github.com/fastapi/fastapi/issues/12323
    当带有 alias 时，接口无法正常工作：
        curl http://127.0.0.1:18081/123
        {"detail":[{"type":"missing","loc":["path","xid"],"msg":"Field required","input":null}]}
    """
    return {'item_id': item_id}

@app.get('/{xid_2}')
async def async_root2(item_id: Annotated[int, Path(title = 'Item ID', alias = 'xid_2')]):
    """
    The title parameter you're referring to in the Path function is part of FastAPI's path parameter customization. While it doesn't directly appear in the Swagger UI documentation, it serves an important purpose in the OpenAPI schema.
    Here's what the title parameter does:
        OpenAPI Schema: The title is included in the OpenAPI (formerly Swagger) schema that FastAPI generates.
                        This schema is a machine-readable description of your API, which can be used by various tools and clients.
        JSON Schema: In the context of JSON Schema (which OpenAPI uses), the title provides a human-readable name for the parameter.
                     It's meant to be a brief description of the parameter.
        API Documentation: While not directly visible in the Swagger UI,
                           the title can be used by other documentation tools that consume the OpenAPI schema to provide more descriptive names for parameters.
        Code Generation: Tools that generate client code from OpenAPI schemas might use the title to create more meaningful variable or property names.
    """
    return {'item_id': item_id}