亚平子
特征
- 生成准备使用
ApiClient有类型( 使用)fetch(中文(简体) ) - 单个输出文件, 最小第三方代码
- 从 JSON / YAML 从本地和远程装入计划
- 定制的能力
fetch带有自定义函数 - 用 Pretier 自动格式化
- 可解析日期- 时间格式( C)
--parse-dates旗帜) - 支持 OpenAPI v2, v3, v3.1
- 也可以与 npx 一起使用
安装
npm install apigen-ts --save-dev
yarn add -D apigen-ts
使用量
1. 生成
# From file
npx apigen-ts ./openapi.json ./api-client.ts
# From url
npx apigen-ts https://petstore3.swagger.io/api/v3/openapi.json ./api-client.ts
# From protected url
npx apigen-ts https://secret-api.example.com ./api-client.ts -H "x-api-key: secret-key"
运行 npx apigen-ts --help 更多选择。 生成客户的例子 这里。 。 。 .
2. 进口
import { ApiClient } from "./api-client"
const api = new ApiClient({
baseUrl: "https://example.com/api",
headers: { Authorization: "secret-token" },
})
3. 使用
// GET /pet/{petId}
await api.pet.getPetById(1) // -> Pet
// GET /pet/findByStatus?status=sold
await api.pet.findPetsByStatus({ status: "sold" }) // -> Pets[]
// PUT /user/{username}; second arg body with type User
await api.user.updateUser("username", { firstName: "John" })
高级
登录流量
const { token } = await api.auth.login({ usename, password })
api.Config.headers = { Authorization: token }
await api.protectedRoute.get() // here authenticated
自动分析日期
npx apigen-ts ./openapi.json ./api-client.ts --parse-dates
const pet = await api.pet.getPetById(1)
const createdAt: Date = pet.createdAt // date parsed from string with format=date-time
字符串结合为 enum
您可以生成字符串字面结合, 而不是本地的enums, 以防你想在 Node.js 环境中运行 类型完成这个传球 --inline-enums 命令行参数或使用 inlineEnums: true 在节点.js API.
npx apigen-ts ./openapi.json ./api-client.ts --inline-enums
这将生成:
type MyEnum = "OptionA" | "OptionB"
// instead of
enum MyEnum = {
OptionA = "OptionA",
OptionB = "OptionB"
}
处理错误
所有未成功返回代码都将被排除.
try {
const pet = await api.pet.getPetById(404)
} catch (e) {
console.log(e) // parse error depend of your domain model, e is awaited response.json()
}
您也可以定义自定义函数来解析错误 :
class MyClient extends ApiClient {
async ParseError(rep: Response) {
// do what you want
return { code: "API_ERROR" }
}
}
try {
const api = new MyClient()
const pet = await api.pet.getPetById(404)
} catch (e) {
console.log(e) // e is { code: "API_ERROR" }
}
基本url 解析
您可以修改端点url的创建方式 。 默认 URL 构建器 用于像 : new URL(path, baseUrl) 具有特定解析 规则例如:
new URL("/v2/cats", "https://example.com/v1/") // -> https://example.com/v2/catsnew URL("v2/cats", "https://example.com/v1/") // -> https://example.com/v1/v2/cats
如果您想要自定义端点 URL 解析规则, 您可以覆盖 PrepareFetchUrl 方法。 详情见 问题。 。 。 .
class MyClient extends ApiClient {
PrepareFetchUrl(path: string) {
return new URL(`${this.Config.baseUrl}/${path}`.replace(/\/{2,}/g, "/"))
}
}
const api = new MyClient({ baseUrl: "https://example.com/v1" })
// will call: https://example.com/v1/pet/ instead of https://example.com/pet/
const pet = await api.pet.getPetById(404)
节点.js API
创建文件像 apigen.mjs 有内容 :
import { apigen } from "apigen-ts"
await apigen({
source: "https://petstore3.swagger.io/api/v3/openapi.json",
output: "./api-client.ts",
// everything below is optional
name: "MyApiClient", // default "ApiClient"
parseDates: true, // default false
inlineEnums: false, // default false, use string literal union instead of enum
headers: { "x-api-key": "secret-key" }, // Custom HTTP headers to use when fetching schema
resolveName(ctx, op, proposal) {
// proposal is [string, string] which represents module.funcName
if (proposal[0] === "users") return // will use default proposal
const [a, b] = op.name.split("/").slice(3, 5) // eg. /api/v1/store/items/search
return [a, `${op.method}_${b}`] // [store, 'get_items'] -> apiClient.store.get_items()
},
})
然后运行 : node apigen.mjs
使用不同的后端框架
FastAPI 软件
默认 apigen-ts 与 FastAPI 一起使用时生成吵闹方法名称。 这可以由 自定义解析 行动编号.
from fastapi import FastAPI
from fastapi.routing import APIRoute
app = FastAPI()
# add your routes here
def update_operation_ids(app: FastAPI) -> None:
for route in app.routes:
if isinstance(route, APIRoute):
ns = route.tags[0] if route.tags else "general"
route.operation_id = f"{ns}_{route.name}".lower()
# this function should be after all routes added
update_operation_ids(app)
注:如果希望FastAPI作为预设添加,请打开PR.
比较
- openapi-typescript-codegen 代码 (单位:千美元)无: 无单一文件模式 1263号
- openapi 类型标记 (单位:千美元)无: 低等 api; 客户端代码中没有要使用的命名类型导出
- opalapi- 生成器- cli (单位:千美元)无:围着java lib打包
- 斯瓦格类型标记- api (单位:千美元)无: 复杂配置; 用户- api 在版本间断开更改