FastAPI系列(2)：路径参数

1. 声明路径参数

# main.py
# coding:utf8

from fastapi import FastAPI


app = FastAPI()


@app.get("/items/{item_id}")  # 路径参数item_id
async def read_item(item_id):  # 此处函数的形参item_id必须和路径参数的名称一致
    return {"item_id": item_id}


if __name__ == '__main__':
    import uvicorn

    uvicorn.run('main:app', host='127.0.0.1', port=8008, reload=True)

上方代码中的路径参数item_id会作为参数传递给函数read_item，此时访问http://127.0.0.1:8008/items/abc 会返回{“item_id”: abc}

浏览器访问

交互式API访问

2. 指定路径参数的类型

# main.py
# coding:utf8

from fastapi import FastAPI


app = FastAPI()


@app.get("/items/{item_id}")  # 路径参数item_id
async def read_item(item_id:int):  # 此处函数的形参item_id必须和路径参数的名称一致
    return {"item_id": item_id}


if __name__ == '__main__':
    import uvicorn

    uvicorn.run('main:app', host='127.0.0.1', port=8008, reload=True)

指定类型前，此参数为必填

指定类型后，此参数为必填且为整形

浏览器正常访问

当传入错误类型时，自动生成错误类型提示信息

3. 路径参数的顺序

# main.py
# coding:utf8

from fastapi import FastAPI


app = FastAPI()

@app.get("/info/me")  # 有默认值的路径参数需要生命在对应的路径参数方法前
async def get_my_info():
    return {"info": 'my info'}

@app.get("/info/{user_id}")  # 如果此路径声明在前，那么/info/me永远不会生效
async def get_user_info(user_id: str):
    return {"info": 'info of '+ user_id}

@app.get("/items/{item_id}")  # 路径参数item_id
async def read_item(item_id:int):  # 此处函数的形参item_id必须和路径参数的名称一致
    return {"item_id": item_id}


if __name__ == '__main__':
    import uvicorn

    uvicorn.run('main:app', host='127.0.0.1', port=8008, reload=True)

注：若路径/info/{user_id}声明在/info/me之前的话，当调用/info/me时，会把me当作user_id传入，则返回的是{“info”: ‘info of me’} 而不会是{“info”: ‘my info’}

4. 预定义路径参数

当某个路径下仅支持特定路径，则可以通过预定义路径来处理。

此处需要借助于Python的枚举类Enum。

# main.py
# coding:utf8

from enum import Enum
from fastapi import FastAPI


app = FastAPI()

class EnumInfo(Enum):
    A = 'mack'
    B = 'alex'
    C = 'tom'


info_dict = {"mack": "I'm mack", "alex": "I'm alex", "tom": "I'm tom"}


@app.get("/info/{info_type}")
async def get_user_info(info_type: EnumInfo):  # 只需要指定路径参数的类型为枚举类即可
    if info_type.value == EnumInfo.A.value:  # 通过枚举类属性的值判断
        return {'info': info_dict['mack']}
    elif info_type == EnumInfo.B:  # 通过枚举类的属性判断
        return {'info': info_type}  # 此处接口返回的也是枚举类属性的值，而不是枚举类属性
    elif info_type.value == 'tom':  # 通过值判断（此处是getattr(EnumInfo,info_type)）
        return {'info': info_dict['tom']}


if __name__ == '__main__':
    import uvicorn

    uvicorn.run('main:app', host='127.0.0.1', port=8008, reload=True)

看交互式API文档，可以看到路径仅支持枚举类属性对应值

5. 路径参数包含路径

# main.py
# coding:utf8

from enum import Enum
from fastapi import FastAPI


app = FastAPI()

@app.get("/file/{file_path:path}")  # 此处指定为路径参数的类型为路径则能够发起类似 /file//home/abc.txt 的请求
async def get_user_info(file_path: str):  # 指定路径参数为字符串类型
    return {'path': file_path}


if __name__ == '__main__':
    import uvicorn

    uvicorn.run('main:app', host='127.0.0.1', port=8008, reload=True)

交互文档&模拟请求结果

6. 其他补充

交互文档接口分类

# main.py
# coding:utf8

from enum import Enum
from fastapi import FastAPI


app = FastAPI()

@app.get("/file/{file_path:path}", tags=['file'])  # 添加接口标签（分类）
async def get_file_path(file_path: str):
    """
    获取文件位置

    - param file_path: 文件路径
    - return:
    """
    return {'path': file_path}


@app.get("/file/detail/{file_id}", tags=['file'])  # 添加接口标签（分类）
async def get_file_detail(file_id: str):
    """
    获取文件详情

    - param file_id: 文件ID
    - return:
    """
    return {'file_detail': file_id}


@app.get("/user/info/me", tags=['user'])  # 添加接口标签（分类）
async def get_my_info():
    """
    获取个人信息
    - return:
    """
    return {'info': 'this is my info'}


@app.get("/user/info/{user_id}", tags=['user'], summary="获取用户信息", )  # 添加接口标签（分类）
async def get_user_info(user_id: str):
    """
    获取用户信息

    - param user_id: 用户ID
    - return:
    """
    return {'info': 'info of ' + user_id}


if __name__ == '__main__':
    import uvicorn

    uvicorn.run('main:app', host='127.0.0.1', port=8008, reload=True)

注：

1. tags对接口进行标签分类管理
2. 交互式文档默认以接口对应的函数名展示，可通过summary来替换展示对应接口的请求方法名
3. 接口的函数写的注释信息可在接口详情中查看
4. 另，可通过deprecated=True来表明此接口已经过期（后文介绍）
5. 另，可通过response_model来指定响应数据模型（后文介绍）

7. 总结

使用 FastAPI，通过简短、直观和标准的 Python 类型声明，你将获得：

• 编辑器支持：错误检查，代码补全等
• 数据 “解析”
• 数据校验
• API 标注和自动生成的文档