orval

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Orval OpenAPI Best Practices

Orval OpenAPI 最佳实践

Comprehensive guide for generating type-safe TypeScript clients from OpenAPI specifications using Orval. Contains 42 rules across 8 categories, prioritized by impact to guide automated configuration, client generation, and testing setup.

本指南全面介绍了如何使用Orval从OpenAPI规范生成类型安全的TypeScript客户端。包含8个类别共42条规则，按影响优先级排序，可指导自动化配置、客户端生成和测试环境搭建。

When to Apply

适用场景

Reference these guidelines when:

Configuring Orval for a new project
Setting up OpenAPI-based TypeScript client generation
Integrating React Query, SWR, or Vue Query with generated hooks
Creating custom mutators for authentication and error handling
Generating MSW mocks for testing

在以下场景中可参考本指南：

配置新项目的Orval时
搭建基于OpenAPI的TypeScript客户端生成流程时
将React Query、SWR或Vue Query与生成的钩子集成时
创建用于身份验证和错误处理的自定义mutator时
生成用于测试的MSW模拟时

Rule Categories by Priority

按优先级划分的规则类别


spec-
orvalcfg-
output-
mutator-
oquery-
types-
mock-
adv-

Priority	Category	Impact	Prefix
1	OpenAPI Specification Quality	CRITICAL	`spec-`
2	Configuration Architecture	CRITICAL	`orvalcfg-`
3	Output Structure & Organization	HIGH	`output-`
4	Custom Client & Mutators	HIGH	`mutator-`
5	Query Library Integration	MEDIUM-HIGH	`oquery-`
6	Type Safety & Validation	MEDIUM	`types-`
7	Mock Generation & Testing	MEDIUM	`mock-`
8	Advanced Patterns	LOW	`adv-`


spec-
orvalcfg-
output-
mutator-
oquery-
types-
mock-
adv-

优先级	类别	影响级别	前缀
1	OpenAPI规范质量	CRITICAL	`spec-`
2	配置架构	CRITICAL	`orvalcfg-`
3	输出结构与组织	HIGH	`output-`
4	自定义客户端与Mutator	HIGH	`mutator-`
5	查询库集成	MEDIUM-HIGH	`oquery-`
6	类型安全与验证	MEDIUM	`types-`
7	模拟生成与测试	MEDIUM	`mock-`
8	高级模式	LOW	`adv-`

Quick Reference

快速参考

1. OpenAPI Specification Quality (CRITICAL)

1. OpenAPI规范质量（CRITICAL）

```
spec-operationid-unique
```
- Use unique and descriptive operationIds
```
spec-schemas-reusable
```
- Define reusable schemas in components
```
spec-tags-organization
```
- Organize operations with tags
```
spec-response-types
```
- Define all response types explicitly
```
spec-required-fields
```
- Mark required fields explicitly

```
spec-operationid-unique
```
- 使用唯一且具有描述性的operationId
```
spec-schemas-reusable
```
- 在components中定义可复用的schema
```
spec-tags-organization
```
- 使用标签对操作进行分类
```
spec-response-types
```
- 显式定义所有响应类型
```
spec-required-fields
```
- 显式标记必填字段

2. Configuration Architecture (CRITICAL)

2. 配置架构（CRITICAL）

```
orvalcfg-mode-selection
```
- Choose output mode based on API size
```
orvalcfg-client-selection
```
- Select client based on framework requirements
```
orvalcfg-separate-schemas
```
- Separate schemas into dedicated directory
```
orvalcfg-input-validation
```
- Validate OpenAPI spec before generation
```
orvalcfg-baseurl-setup
```
- Configure base URL properly
```
orvalcfg-prettier-format
```
- Enable automatic code formatting

```
orvalcfg-mode-selection
```
- 根据API规模选择输出模式
```
orvalcfg-client-selection
```
- 根据框架需求选择客户端类型
```
orvalcfg-separate-schemas
```
- 将schema分离到专用目录
```
orvalcfg-input-validation
```
- 生成前验证OpenAPI规范
```
orvalcfg-baseurl-setup
```
- 正确配置基础URL
```
orvalcfg-prettier-format
```
- 启用自动代码格式化

3. Output Structure & Organization (HIGH)

3. 输出结构与组织（HIGH）

```
output-file-extension
```
- Use distinct file extensions for generated code
```
output-index-files
```
- Generate index files for clean imports
```
output-naming-convention
```
- Configure consistent naming conventions
```
output-clean-target
```
- Enable clean mode for consistent regeneration
```
output-headers-enabled
```
- Enable headers in generated functions

```
output-file-extension
```
- 为生成的代码使用不同的文件扩展名
```
output-index-files
```
- 生成索引文件以优化导入体验
```
output-naming-convention
```
- 配置统一的命名规范
```
output-clean-target
```
- 启用清理模式以确保一致的重新生成
```
output-headers-enabled
```
- 在生成的函数中启用头部支持

4. Custom Client & Mutators (HIGH)

4. 自定义客户端与Mutator（HIGH）

```
mutator-custom-instance
```
- Use custom mutator for HTTP client configuration
```
mutator-error-types
```
- Export custom error types from mutator
```
mutator-body-wrapper
```
- Export body type wrapper for request transformation
```
mutator-interceptors
```
- Use interceptors for cross-cutting concerns
```
mutator-token-refresh
```
- Handle token refresh in mutator
```
mutator-fetch-client
```
- Use fetch mutator for smaller bundle size

```
mutator-custom-instance
```
- 使用自定义mutator配置HTTP客户端
```
mutator-error-types
```
- 从mutator导出自定义错误类型
```
mutator-body-wrapper
```
- 导出请求体类型包装器以实现请求转换
```
mutator-interceptors
```
- 使用拦截器处理横切关注点
```
mutator-token-refresh
```
- 在mutator中处理令牌刷新逻辑
```
mutator-fetch-client
```
- 使用fetch mutator以减小包体积

5. Query Library Integration (MEDIUM-HIGH)

5. 查询库集成（MEDIUM-HIGH）

```
oquery-hook-options
```
- Configure default query options globally
```
oquery-key-export
```
- Export query keys for cache invalidation
```
oquery-infinite-queries
```
- Enable infinite queries for paginated endpoints
```
oquery-suspense-support
```
- Enable suspense mode for streaming UX
```
oquery-signal-cancellation
```
- Pass AbortSignal for request cancellation
```
oquery-mutation-callbacks
```
- Use generated mutation options types

```
oquery-hook-options
```
- 全局配置默认查询选项
```
oquery-key-export
```
- 导出查询键以实现缓存失效
```
oquery-infinite-queries
```
- 为分页端点启用无限查询
```
oquery-suspense-support
```
- 启用suspense模式以实现流式用户体验
```
oquery-signal-cancellation
```
- 传递AbortSignal以支持请求取消
```
oquery-mutation-callbacks
```
- 使用生成的突变选项类型

6. Type Safety & Validation (MEDIUM)

6. 类型安全与验证（MEDIUM）

```
types-zod-validation
```
- Generate Zod schemas for runtime validation
```
types-zod-strict
```
- Enable Zod strict mode for safer validation
```
types-zod-coerce
```
- Use Zod coercion for type transformations
```
types-use-dates
```
- Enable useDates for Date type generation
```
types-bigint-support
```
- Enable useBigInt for large integer support

```
types-zod-validation
```
- 生成Zod schema以实现运行时验证
```
types-zod-strict
```
- 启用Zod严格模式以提升验证安全性
```
types-zod-coerce
```
- 使用Zod强制转换实现类型转换
```
types-use-dates
```
- 启用useDates以生成Date类型
```
types-bigint-support
```
- 启用useBigInt以支持大整数

7. Mock Generation & Testing (MEDIUM)

7. 模拟生成与测试（MEDIUM）

```
mock-msw-generation
```
- Generate MSW handlers for testing
```
mock-use-examples
```
- Use OpenAPI examples for realistic mocks
```
mock-delay-config
```
- Configure mock response delays
```
mock-http-status
```
- Generate mocks for all HTTP status codes
```
mock-index-files
```
- Generate mock index files for easy setup

```
mock-msw-generation
```
- 生成MSW处理程序用于测试
```
mock-use-examples
```
- 使用OpenAPI示例生成真实感模拟数据
```
mock-delay-config
```
- 配置模拟响应延迟
```
mock-http-status
```
- 为所有HTTP状态码生成模拟
```
mock-index-files
```
- 生成模拟索引文件以简化配置

8. Advanced Patterns (LOW)

8. 高级模式（LOW）

```
adv-input-transformer
```
- Use input transformer for spec preprocessing
```
adv-operation-override
```
- Override settings per operation
```
adv-output-transformer
```
- Use output transformer for generated code modification
```
adv-form-data-handling
```
- Configure form data serialization

```
adv-input-transformer
```
- 使用输入转换器预处理规范
```
adv-operation-override
```
- 按操作覆盖配置
```
adv-output-transformer
```
- 使用输出转换器修改生成的代码
```
adv-form-data-handling
```
- 配置表单数据序列化

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules
Example: spec-operationid-unique

阅读单个参考文件以获取详细说明和代码示例：

章节定义 - 类别结构和影响级别说明
规则模板 - 添加新规则的模板
示例：spec-operationid-unique

Related Skills

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

包含所有规则详细说明的完整指南：

AGENTS.md