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 的版本历史、贡献者列表、相关资源的链接等。