简聊Fastapi框架中的OpenAPI规范

2024年 1月 2日 43.9k 0

OpenAPI规范(也称为Swagger规范),在Fastapi框架中它主要用来定义和文档化API接口。

关于OpenAPI规范是一种用于描述和定义Web API的标准化规范。它可以使用JSON或YAML等格式来描述API的各种元数据信息等细节,如接口路径、请求方法、请求和响应的数据结构、参数、错误处理等。

通过使用OpenAPI规范,我们可以轻松地生成API文档,并且可以使用各种工具来自动生成客户端代码、进行接口测试等。如Swagger UI,项目启动后就可以查看到具体的路由定义信息,并可以进行调试等。

在整个框架应用中主要表现为:我们可以通过使用装饰器和Python类型提示来定义API接口相关信息。框架本身会根据我们定义的一些相关规则信息自动生成OpenAPI文档,并提供一个交互式的API文档页面,可以在其中查看和测试API接口。 这个文档页面基于Swagger UI,它可以根据OpenAPI规范自动生成,并提供了一些方便的功能,比如请求参数的验证和自动生成请求示例等。

应用主要场景:

我们可以使用OpenAPI规范来定义接口的各种细节,其中可以包括请求和响应的数据结构、参数、错误处理等信息。这样可以使得我们的API接口更加清晰、易于理解和使用。

1.定义应用app对象的元数据

python
from fastapi import FastAPI

app = FastAPI(title="项目标题I", description="项目文档描述", version="1.0.0")

在上面的代码中,主要是通过参数定义为我应用示例对应的以及相关API元数据,例如标题、描述和版本号。

2.定义路由的元数据

@app.get("/items/{item_id}", summary="路由标题", description="路由描述说明")
def get_item(item_id: int):
    return {"item_id": item_id}

在上面的代码中,主要是通过装饰器参数为路由添加元数据,例如摘要和描述信息。 当然还有其他的参数可以传入。

3.定义模型的元数据

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str = Field(..., description="描述信息")

OpenAPI 自定义和扩展

1.示例

在fastapi框架提供了一个openapi的自定义参数,如下代码所示:

app.openapi = custom_openapi

基于上面的openapi我就可有针对进行扩展和自定义其他扩展字段信息,如下示例代码:

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="FastAPIBoilerplate",
        version="0.0.1",
        summary="FastAPIBoilerplate",
        description='框架模板',
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https:xxxxxxxx"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema

如上代码中:我们通过获取app实例对象中已自动生成的 OpenAPI 规范后,在它毒药的 info 对象中添加一个 x-custom 字段。这个字段可以是任何 JSON 兼容的数据,例如字符串、数字、布尔值、列表或字典。如此完成后,当我们访问:

http://127.0.0.1:31120/openapi.json

即可获取到如下图所示的结果:

当然我们还可以扩展其他的参数项: 如下代码所示:

 openapi_schema["info"]["x-custom"] = "自定义数据信息"

2.自定义和扩展作用和说明

一般通过在 OpenAPI 规范中添加额外的、非标准的信息一般可以用于:

  • 提供额外的文档信息。
  • 集成其他工具参数信息。
  • 包含额外的元数据。如 API 的版本历史、贡献者列表、相关资源的链接等。

相关文章

JavaScript2024新功能:Object.groupBy、正则表达式v标志
PHP trim 函数对多字节字符的使用和限制
新函数 json_validate() 、randomizer 类扩展…20 个PHP 8.3 新特性全面解析
使用HTMX为WordPress增效:如何在不使用复杂框架的情况下增强平台功能
为React 19做准备:WordPress 6.6用户指南
如何删除WordPress中的所有评论

发布评论