简聊Fastapi框架中的OpenAPI规范-51CTO.COM

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