FastAPI系列16：从API文档到TypeScript 前端客户端（SDKs）

---

在 FastAPI系列15：API文档的定制和美化 一节中，我们讲解了如何定制和美化API文档，一个良好的API文档可以过千言万语的沟通，同时也能让你立刻收获一个结构良好的客户端框架。本节我们介绍如何使用openapi-ts为你的API生成一个TypeScript 前端客户端。

我们知道FastAPI是基于OpenAPI规范的，这就意味着我们可以使用一些工具来为不同的编程语言生成客户端（SDKs），如：

• OpenAPI Generator
• openapi-ts

快速入门

我们有一个简单的 FastAPI 应用：

from fastapi import FastAPI
from pydantic import BaseModelapp = FastAPI()class Item(BaseModel):name: strprice: floatclass ResponseMessage(BaseModel):message: str@app.post("/items/", response_model=ResponseMessage)
async def create_item(item: Item):return {"message": "item received"}@app.get("/items/", response_model=list[Item])
async def get_items():return [{"name": "Plumbus", "price": 3},{"name": "Portal Gun", "price": 9001},]

生成一个TypeScript 客户端

安装 openapi-ts

npm install @hey-api/openapi-ts --save-dev

生成客户端代码
配置好package.json

{"name": "frontend-app","version": "1.0.0","description": "","main": "index.js","scripts": {"generate-client": "openapi-ts --input http://localhost:8000/openapi.json --output ./src/client --client axios"},"author": "","license": "","devDependencies": {"@hey-api/openapi-ts": "^0.27.38","typescript": "^4.6.2"}
}

运行generate-client脚本

npm run generate-client

这时我们就可以在./src/client中获得生成的代码。

测试生成的TypeScript 客户端

现在我们可以导入并使用客户端代码：

我们可以方便地在客户端代码中使用自动补全

API标签与客户端生成

在复杂一些的情况下，我们会使用标签来分隔不同组的路由，如下列代码情形：

from fastapi import FastAPI
from pydantic import BaseModelapp = FastAPI()class Item(BaseModel):name: strprice: floatclass ResponseMessage(BaseModel):message: strclass User(BaseModel):username: stremail: str@app.post("/items/", response_model=ResponseMessage, tags=["items"])
async def create_item(item: Item):return {"message": "Item received"}@app.get("/items/", response_model=list[Item], tags=["items"])
async def get_items():return [{"name": "Plumbus", "price": 3},{"name": "Portal Gun", "price": 9001},]@app.post("/users/", response_model=ResponseMessage, tags=["users"])
async def create_user(user: User):return {"message": "User received"}

生成带有标签的 TypeScript 客户端

当我们重新执行generate-client脚本，它会根据tags为我们生成两个service：ItemsService、UserService。

自定义Operation ID

在生成的代码中，类似于createItemItemsPost这样的方法名看起来不太简洁，这是因为OpenAPI要求每个Operation ID 都是唯一的，所以FastAPI会默认使用函数名、路径和HTTP方法/操作来生成Operation ID。
当然，我们也是可以通过自定义函数来修改这些Operation ID的生成方式。这个自定义函数要求接受一个 APIRoute 对象作为参数，结果输出一个字符串作为Operation ID：

from fastapi import FastAPI
from fastapi.routing import APIRoute
from pydantic import BaseModeldef custom_generate_unique_id(route: APIRoute):return f"{route.tags[0]}-{route.name}"app = FastAPI(generate_unique_id_function=custom_generate_unique_id)class Item(BaseModel):name: strprice: floatclass ResponseMessage(BaseModel):message: strclass User(BaseModel):username: stremail: str@app.post("/items/", response_model=ResponseMessage, tags=["items"])
async def create_item(item: Item):return {"message": "Item received"}@app.get("/items/", response_model=list[Item], tags=["items"])
async def get_items():return [{"name": "Plumbus", "price": 3},{"name": "Portal Gun", "price": 9001},]@app.post("/users/", response_model=ResponseMessage, tags=["users"])
async def create_user(user: User):return {"message": "User received"}

使用自定义Operation ID生成TypeScript客户端

现在再次生成客户端，我们就可以获得更好的方法名了：