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 BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float


class 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 BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float


class ResponseMessage(BaseModel):
    message: str


class User(BaseModel):
    username: str
    email: 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 BaseModel


def 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: str
    price: float


class ResponseMessage(BaseModel):
    message: str


class User(BaseModel):
    username: str
    email: 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客户端

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