orval by orval-labs/orval
npx skills add https://github.com/orval-labs/orval --skill orvalOrval 能够根据 OpenAPI v3/Swagger v2 规范生成类型安全的 TypeScript 客户端、钩子、模式、模拟数据以及服务器处理器。
npm install orval -D
# or yarn add orval -D
# or pnpm add orval -D
# or bun add orval -D
import { defineConfig } from 'orval';
export default defineConfig({
petstore: {
input: {
target: './petstore.yaml',
},
output: {
target: './src/api/petstore.ts',
schemas: './src/api/model',
client: 'react-query',
},
},
});
npx orval
npx orval --config ./orval.config.ts
npx orval --project petstore
npx orval --watch
| 使用场景 | 客户端 | httpClient | 备注 |
|---|
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| React 配合服务器状态管理 | react-query | fetch 或 axios | TanStack Query 钩子 |
| Vue 3 配合服务器状态管理 | vue-query | fetch 或 axios | Vue 版 TanStack Query |
| Svelte 配合服务器状态管理 | svelte-query | fetch 或 axios | Svelte 版 TanStack Query |
| SolidJS 独立应用 | solid-query | fetch 或 axios | Solid 版 TanStack Query |
| SolidStart 全栈应用 | solid-start | 原生 fetch | 使用 query()/action() 原语 |
| Angular 配合信号 | angular-query | angular | 可注入函数,信号响应式 |
| Angular 传统方式 | angular | — | HttpClient 服务 |
| React 配合 SWR | swr | fetch 或 axios | Vercel SWR 钩子 |
| 轻量级 / 边缘环境 | fetch | — | 零依赖,随处可用 |
| Node.js / 已有 Axios | axios-functions | — | 工厂函数(默认) |
| Axios 配合依赖注入 | axios | — | 可注入的 Axios 实例 |
| 仅验证 | zod | — | Zod 模式,无 HTTP 客户端 |
| 后端 API 服务器 | hono | — | 带 Zod 验证的 Hono 处理器 |
| AI 代理工具 | mcp | — | 模型上下文协议服务器 |
single — 所有内容在一个文件中。最适合小型 API。split — 分离文件:petstore.ts、petstore.schemas.ts、petstore.msw.ts。适合中型 API。tags — 每个 OpenAPI 标签一个文件 + 共享模式。按领域组织。tags-split — 每个标签一个文件夹,内含分离的文件。最适合大型 API。推荐使用。对于 react-query、vue-query、svelte-query 和 swr 客户端:
output: {
client: 'react-query',
httpClient: 'fetch', // 'fetch' (默认) | 'axios'
}
对于 angular-query:
output: {
client: 'angular-query',
httpClient: 'angular', // 使用 Angular HttpClient
}
import { defineConfig } from 'orval';
export default defineConfig({
[projectName]: {
input: InputOptions,
output: OutputOptions,
hooks: HooksOptions,
},
});
多个项目可以共享同一个配置文件,但具有不同的输入/输出设置。
input: {
target: './spec.yaml', // OpenAPI 规范的路径或 URL (必需)
override: {
transformer: './transform.js', // 在生成前转换规范
},
filters: {
mode: 'include', // 'include' | 'exclude'
tags: ['pets', /health/], // 按 OpenAPI 标签过滤
schemas: ['Pet', /Error/], // 按模式名称过滤
},
parserOptions: {
headers: [ // 用于远程规范 URL 的认证头
{
domains: ['api.example.com'],
headers: {
Authorization: 'Bearer YOUR_TOKEN',
'X-API-Key': 'your-api-key',
},
},
],
},
}
output: {
target: './src/api/endpoints.ts', // 输出路径 (必需)
client: 'react-query', // 客户端类型 (见上表)
httpClient: 'fetch', // 'fetch' (默认) | 'axios' | 'angular'
mode: 'tags-split', // 'single' | 'split' | 'tags' | 'tags-split'
schemas: './src/api/model', // 模型类型的输出路径
operationSchemas: './src/api/params', // 操作衍生类型的独立路径
workspace: 'src/', // 所有文件的基础文件夹
fileExtension: '.ts', // 自定义文件扩展名
namingConvention: 'camelCase', // 文件命名:camelCase | PascalCase | snake_case | kebab-case
indexFiles: true, // 生成 index.ts 桶文件
clean: true, // 生成前清理输出
prettier: true, // 使用 Prettier 格式化
biome: true, // 使用 Biome 格式化
headers: true, // 生成头部参数
baseUrl: '/api/v2', // API 基础 URL
// 或从规范中获取:
// baseUrl: { getBaseUrlFromSpecification: true, index: 0, variables: { environment: 'api.dev' } },
mock: true, // 生成 MSW 处理器 (布尔值或配置对象)
docs: true, // 生成 TypeDoc 文档
// docs: { configPath: './typedoc.config.mjs' },
allParamsOptional: true, // 使所有参数可选 (路径参数除外)
urlEncodeParameters: true, // URL 编码路径/查询参数
optionsParamRequired: false, // 使 options 参数为必需
propertySortOrder: 'Specification', // 'Alphabetical' | 'Specification'
tsconfig: './tsconfig.json', // 自定义 tsconfig 路径
override: { ... }, // 高级覆盖 (见下文)
}
export default defineConfig({
petstoreV1: {
input: { target: './specs/v1.yaml' },
output: { target: 'src/api/v1', client: 'react-query' },
},
petstoreV2: {
input: { target: './specs/v2.yaml' },
output: { target: 'src/api/v2', client: 'react-query' },
},
});
input: {
target: './spec.yaml',
filters: {
mode: 'include',
tags: ['pets'],
},
}
当用户的问题涉及以下特定主题时,请从本技能的目录中读取相应的文件。
| 主题 | 文件 | 当用户询问关于...时加载 |
|---|---|---|
| TanStack Query / SWR | tanstack-query.md | React Query, Vue Query, Svelte Query, Solid Query, SWR, 查询钩子, 失效, 无限查询, 悬念, 预取 |
| Angular | angular.md | Angular Query, Angular HttpClient, 信号, 注入函数, Angular 服务, providedIn |
| SolidStart | solid-start.md | SolidStart, @solidjs/router, query(), action(), createAsync, 重新验证 |
| 自定义 HTTP / 认证 | custom-http-clients.md | 自定义 mutator, 认证, 令牌, 拦截器, 自定义 fetch/axios, baseURL, 基于钩子的 mutator |
| Zod 验证 | zod-validation.md | Zod 模式, 验证, 运行时验证, 强制转换, 严格模式, 预处理 |
| 模拟 / MSW | mocking-msw.md | MSW 模拟, 测试, 测试设置, faker, Vitest, 模拟处理器, useExamples |
| Hono 服务器 | hono.md | Hono 处理器, zValidator, 复合路由, 上下文类型, 服务器端生成 |
| 高级配置 | advanced-config.md | 类型生成, 枚举, 每个操作的覆盖, FormData, JSDoc, 参数序列化器, 完整示例 |
| 工具 / 工作流 | tooling-workflow.md | 编程式 API, 转换器, 钩子, NDJSON 流, MCP, afterAllFilesWrite |
operationId — Orval 使用这些来命名函数和钩子components/schemas 中定义可重用的模式 — 减少生成类型中的重复tags 和 tags-split 模式配合使用x-enumNames — 生成可读的常量名称example 值 — 当 useExamples: true 时用于模拟生成application/x-ndjson 内容类型 — 启用类型化的 NDJSON 生成orval # 使用自动发现的配置生成
orval --config ./api/orval.config.ts # 指定配置文件
orval --project petstore # 运行特定项目
orval --watch # 监视模式
orval --watch ./src # 监视特定目录
orval --clean # 清理生成的文件
orval --prettier # 使用 Prettier 格式化
orval --biome # 使用 Biome 格式化
orval --tsconfig ./src/tsconfig.json # 自定义 tsconfig 路径
orval --mode split # 覆盖输出模式
orval --client react-query # 覆盖客户端
orval --mock # 覆盖模拟生成
orval --input ./spec.yaml --output ./api.ts # 直接生成
每周安装量
74
代码仓库
GitHub 星标
5.6K
首次出现
2026年2月17日
安全审计
安装于
github-copilot73
kimi-cli72
gemini-cli72
amp72
codex72
opencode72
Orval generates type-safe TypeScript clients, hooks, schemas, mocks, and server handlers from OpenAPI v3/Swagger v2 specifications.
npm install orval -D
# or yarn add orval -D
# or pnpm add orval -D
# or bun add orval -D
import { defineConfig } from 'orval';
export default defineConfig({
petstore: {
input: {
target: './petstore.yaml',
},
output: {
target: './src/api/petstore.ts',
schemas: './src/api/model',
client: 'react-query',
},
},
});
npx orval
npx orval --config ./orval.config.ts
npx orval --project petstore
npx orval --watch
| Use Case | Client | httpClient | Notes |
|---|---|---|---|
| React with server state | react-query | fetch or axios | TanStack Query hooks |
| Vue 3 with server state | vue-query | fetch or axios | TanStack Query for Vue |
| Svelte with server state | svelte-query | fetch or axios |
single — Everything in one file. Best for small APIs.split — Separate files: petstore.ts, petstore.schemas.ts, petstore.msw.ts. Good for medium APIs.tags — One file per OpenAPI tag + shared schemas. Organizes by domain.tags-split — Folder per tag with split files. Best for large APIs. Recommended.For react-query, vue-query, svelte-query, and swr clients:
output: {
client: 'react-query',
httpClient: 'fetch', // 'fetch' (default) | 'axios'
}
For angular-query:
output: {
client: 'angular-query',
httpClient: 'angular', // Uses Angular HttpClient
}
import { defineConfig } from 'orval';
export default defineConfig({
[projectName]: {
input: InputOptions,
output: OutputOptions,
hooks: HooksOptions,
},
});
Multiple projects can share the same config file with different input/output settings.
input: {
target: './spec.yaml', // Path or URL to OpenAPI spec (required)
override: {
transformer: './transform.js', // Transform spec before generation
},
filters: {
mode: 'include', // 'include' | 'exclude'
tags: ['pets', /health/], // Filter by OpenAPI tags
schemas: ['Pet', /Error/], // Filter by schema names
},
parserOptions: {
headers: [ // Auth headers for remote spec URLs
{
domains: ['api.example.com'],
headers: {
Authorization: 'Bearer YOUR_TOKEN',
'X-API-Key': 'your-api-key',
},
},
],
},
}
output: {
target: './src/api/endpoints.ts', // Output path (required)
client: 'react-query', // Client type (see table above)
httpClient: 'fetch', // 'fetch' (default) | 'axios' | 'angular'
mode: 'tags-split', // 'single' | 'split' | 'tags' | 'tags-split'
schemas: './src/api/model', // Output path for model types
operationSchemas: './src/api/params', // Separate path for operation-derived types
workspace: 'src/', // Base folder for all files
fileExtension: '.ts', // Custom file extension
namingConvention: 'camelCase', // File naming: camelCase | PascalCase | snake_case | kebab-case
indexFiles: true, // Generate index.ts barrel files
clean: true, // Clean output before generating
prettier: true, // Format with Prettier
biome: true, // Format with Biome
headers: true, // Generate header parameters
baseUrl: '/api/v2', // API base URL
// or from spec:
// baseUrl: { getBaseUrlFromSpecification: true, index: 0, variables: { environment: 'api.dev' } },
mock: true, // Generate MSW handlers (boolean or config object)
docs: true, // Generate TypeDoc documentation
// docs: { configPath: './typedoc.config.mjs' },
allParamsOptional: true, // Make all params optional (except path params)
urlEncodeParameters: true, // URL-encode path/query parameters
optionsParamRequired: false, // Make options parameter required
propertySortOrder: 'Specification', // 'Alphabetical' | 'Specification'
tsconfig: './tsconfig.json', // Custom tsconfig path
override: { ... }, // Advanced overrides (see below)
}
export default defineConfig({
petstoreV1: {
input: { target: './specs/v1.yaml' },
output: { target: 'src/api/v1', client: 'react-query' },
},
petstoreV2: {
input: { target: './specs/v2.yaml' },
output: { target: 'src/api/v2', client: 'react-query' },
},
});
input: {
target: './spec.yaml',
filters: {
mode: 'include',
tags: ['pets'],
},
}
When the user's question involves a specific topic below, read the corresponding file from this skill's directory.
| Topic | File | Load when user asks about... |
|---|---|---|
| TanStack Query / SWR | tanstack-query.md | React Query, Vue Query, Svelte Query, Solid Query, SWR, query hooks, invalidation, infinite queries, suspense, prefetch |
| Angular | angular.md | Angular Query, Angular HttpClient, signals, inject functions, Angular services, providedIn |
| SolidStart | solid-start.md | SolidStart, @solidjs/router, query(), action(), createAsync, revalidate |
| Custom HTTP / Auth | custom-http-clients.md | Custom mutator, authentication, tokens, interceptors, custom fetch/axios, baseURL, hook-based mutator |
| Zod Validation | zod-validation.md | Zod schemas, validation, runtime validation, coerce, strict, preprocess |
operationId for every operation — Orval uses these for function and hook namescomponents/schemas — reduces duplication in generated typestags and tags-split modesx-enumNames for numeric enums — generates readable const namesexample values — used by mock generation when useExamples: trueorval # Generate using auto-discovered config
orval --config ./api/orval.config.ts # Specify config file
orval --project petstore # Run specific project(s)
orval --watch # Watch mode
orval --watch ./src # Watch specific directory
orval --clean # Clean generated files
orval --prettier # Format with Prettier
orval --biome # Format with Biome
orval --tsconfig ./src/tsconfig.json # Custom tsconfig path
orval --mode split # Override output mode
orval --client react-query # Override client
orval --mock # Override mock generation
orval --input ./spec.yaml --output ./api.ts # Direct generation
Weekly Installs
74
Repository
GitHub Stars
5.6K
First Seen
Feb 17, 2026
Security Audits
Gen Agent Trust HubWarnSocketPassSnykWarn
Installed on
github-copilot73
kimi-cli72
gemini-cli72
amp72
codex72
opencode72
飞书OpenAPI Explorer:探索和调用未封装的飞书原生API接口
37,900 周安装
| TanStack Query for Svelte |
| SolidJS standalone app | solid-query | fetch or axios | TanStack Query for Solid |
| SolidStart full-stack | solid-start | native fetch | Uses query()/action() primitives |
| Angular with signals | angular-query | angular | Injectable functions, signal reactivity |
| Angular traditional | angular | — | HttpClient services |
| React with SWR | swr | fetch or axios | Vercel SWR hooks |
| Lightweight / Edge | fetch | — | Zero dependencies, works everywhere |
| Node.js / existing Axios | axios-functions | — | Factory functions (default) |
| Axios with DI | axios | — | Injectable Axios instance |
| Validation only | zod | — | Zod schemas, no HTTP client |
| Backend API server | hono | — | Hono handlers with Zod validation |
| AI agent tools | mcp | — | Model Context Protocol servers |
| Mocking / MSW | mocking-msw.md | MSW mocks, testing, test setup, faker, Vitest, mock handlers, useExamples |
| Hono Server | hono.md | Hono handlers, zValidator, composite routes, context types, server-side generation |
| Advanced Config | advanced-config.md | Type generation, enums, per-operation overrides, FormData, JSDoc, params serializer, full example |
| Tooling / Workflow | tooling-workflow.md | Programmatic API, transformers, hooks, NDJSON streaming, MCP, afterAllFilesWrite |
application/x-ndjson