OpenAPI 通用生成（模型 + 请求框架）

使用底层命令，不包含本地脚本包装。

前置条件

在目标项目安装 aptx 包，并确保可执行 aptx-ft：

pnpm add -D @aptx/frontend-tk-cli

命令选择

当前项目使用空格分隔命令：aptx-ft <namespace> <command>。

• model gen：生成模型层。
• aptx functions：生成端点定义（spec/）+ 函数式请求封装（functions/）。
• aptx react-query：生成 React Query hooks（依赖 spec/，需先运行 aptx functions）。
• aptx vue-query：生成 Vue Query composables（依赖 spec/，需先运行 aptx functions）。

重要：react-query 和 vue-query 渲染器不会生成 spec/ 端点定义，它们只是引用 functions 渲染器生成的 spec 文件。因此使用 Query 渲染器前必须先运行 aptx functions。

先执行 pnpm exec aptx-ft --help 确认可用命令，不假设历史命令或未注册渲染器仍可用。

参数路径说明

以下参数路径均相对于运行命令时的工作目录（即项目根目录），而非相对于输出目录。

参数	说明	示例
-i	OpenAPI 文件路径	./openapi.json
-o	输出目录	./src/api
--model-path	模型目录（当 --model-mode relative 时）	./src/domains

假设项目结构：

project/
├── openapi.json
└── src/
    ├── domains/    # 模型目录
    └── api/        # API 输出目录

在项目根目录运行：

# model-path 相对于工作目录，而非相对于 ./src/api
pnpm exec aptx-ft aptx react-query -i ./openapi.json -o ./src/api \
  --model-mode relative --model-path ./src/domains

---

项目类型参数建议（执行前必须确认）

先判断项目类型，再给出建议参数；必须等待用户确认最终参数后再执行命令。

单项目（应用代码在 src/）

• 推荐输出：-o ./src/api
• 模型通常在同仓：--model-mode relative --model-path ./src/models
• 客户端通常全局：--client-mode global

示例（react-query）：

pnpm exec aptx-ft aptx react-query -i ./openapi.json -o ./src/api \
  --client-mode global --model-mode relative --model-path ./src/models

Monorepo（模型在独立 package）

• 推荐输出：-o ./apps/<app>/src/api（按实际 app 调整）
• 模型在独立包时优先包导入：--model-mode package --model-path @org/models
• 客户端按项目约定选择 global/local/package

示例（react-query）：

pnpm exec aptx-ft aptx react-query -i ./openapi.json -o ./apps/web/src/api \
  --client-mode package --client-package @org/api-client \
  --model-mode package --model-path @org/models

执行步骤

1. 准备 OpenAPI 输入

本地文件或 URL。

2. 给出参数建议并等待用户确认

1. 根据项目类型给出 single-project 和 monorepo 的参数建议。
2. 明确询问用户确认最终命令（包含 -i/-o、client 参数、model 参数）。
3. 仅在用户确认后执行生成。

3. 生成模型层

pnpm exec aptx-ft -i <spec-file-or-url> model gen --output <models-dir> --style module

4. 生成请求框架

@aptx React Query 示例：

pnpm exec aptx-ft aptx react-query -i <spec-file-or-url> -o ./src/api

@aptx Vue Query 示例：

pnpm exec aptx-ft aptx vue-query -i <spec-file-or-url> -o ./src/api

@aptx Functions 示例：

pnpm exec aptx-ft aptx functions -i <spec-file-or-url> -o ./src/api

5. 客户端配置（仅 @aptx 渲染器）

@aptx 渲染器支持客户端导入配置：

# 全局模式（默认）：使用 @aptx/api-client 的全局实例
pnpm exec aptx-ft aptx react-query -i openapi.json -o ./src/api

# 本地模式：使用本地客户端路径
pnpm exec aptx-ft aptx react-query -i openapi.json -o ./src/api \
  --client-mode local --client-path ./api/client

# 包模式：使用自定义包名
pnpm exec aptx-ft aptx react-query -i openapi.json -o ./src/api \
  --client-mode package --client-package @my-org/api-client

完整示例

React + @aptx 项目

# 1. 安装依赖
pnpm add @aptx/api-client @aptx/api-query-react

# 2. 生成模型
pnpm exec aptx-ft -i ./openapi.json model gen --output ./src/models --style module

# 3. 生成端点定义（spec/）和函数封装（functions/）
pnpm exec aptx-ft aptx functions -i ./openapi.json -o ./src/api

# 4. 生成 React Query Hooks（依赖 spec/）
pnpm exec aptx-ft aptx react-query -i ./openapi.json -o ./src/api

Vue + @aptx 项目

# 1. 安装依赖
pnpm add @aptx/api-client @aptx/api-query-vue

# 2. 生成模型
pnpm exec aptx-ft -i ./openapi.json model gen --output ./src/models --style module

# 3. 生成端点定义（spec/）和函数封装（functions/）
pnpm exec aptx-ft aptx functions -i ./openapi.json -o ./src/api

# 4. 生成 Vue Query Composables（依赖 spec/）
pnpm exec aptx-ft aptx vue-query -i ./openapi.json -o ./src/api

输出结构

aptx functions 输出

src/api/
├── spec/
│   └── namespace/
│       └── xxx.ts           # 端点定义（buildXXXSpec）
└── functions/
    └── namespace/
        └── xxx.ts           # 函数式调用

aptx react-query 输出（需先运行 aptx functions）

src/api/
├── spec/                    # 由 aptx functions 生成
│   └── namespace/
│       └── xxx.ts
└── react-query/
    └── namespace/
        ├── xxx.query.ts     # Query Hook
        └── xxx.mutation.ts  # Mutation Hook

aptx vue-query 输出（需先运行 aptx functions）

src/api/
├── spec/                    # 由 aptx functions 生成
│   └── namespace/
│       └── xxx.ts
└── vue-query/
    └── namespace/
        ├── xxx.query.ts     # Query Composable
        └── xxx.mutation.ts  # Mutation Composable

边界

通用技能不处理业务框架特化逻辑，也不处理 Materal 专用枚举语义化。
Materal 等特化枚举流程请使用 adapt-materal-enums。