Back to Details

openapi

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenAPI

OpenAPI

Overview

概述

OpenAPI Specification (OAS) 3.1 is the industry standard for describing HTTP APIs. It defines a machine-readable contract covering endpoints, request/response schemas, authentication, and error formats. OpenAPI 3.1 is a strict superset of JSON Schema Draft 2020-12, enabling full JSON Schema compatibility for data validation and type generation.
When to use: Designing REST APIs, generating typed clients (TypeScript, Python, Go), producing interactive documentation, validating request/response payloads, contract-first API development, API gateway configuration.
When NOT to use: GraphQL APIs (use the GraphQL schema), gRPC services (use Protocol Buffers), WebSocket-only protocols, internal function calls that never cross a network boundary.
OpenAPI 规范（OAS）3.1 是描述 HTTP API 的行业标准。它定义了一种机器可读的契约，涵盖端点、请求/响应 Schema、认证和错误格式。OpenAPI 3.1 是 JSON Schema Draft 2020-12 的严格超集，支持完全兼容 JSON Schema 的数据验证和类型生成。
适用场景： 设计 REST API、生成类型化客户端（TypeScript、Python、Go）、制作交互式文档、验证请求/响应负载、契约优先的 API 开发、API 网关配置。
不适用场景： GraphQL API（请使用 GraphQL Schema）、gRPC 服务（请使用 Protocol Buffers）、仅 WebSocket 协议、不跨网络边界的内部函数调用。

Quick Reference

快速参考

PatternElementKey Points
Document root
openapi
, 
info
, 
paths
openapi: '3.1.0'
required at top level
Path item
/resources/{id}
Curly braces for path parameters
Operation
get
, 
post
, 
put
, 
delete
, 
patch
Each operation needs 
operationId
and 
responses
Parameters
in: path|query|header|cookie
Path params are always 
required: true
Request body
requestBody.content
Keyed by media type (
application/json
)
Response
responses.200.content
At least one response required per operation
Component ref
$ref: '#/components/schemas/Name'
Reuse schemas, parameters, responses
Schema types
type: string|number|integer|boolean|array|object
Arrays support 
type: ["string", "null"]
in 3.1
Composition
oneOf
, 
anyOf
, 
allOf
Model polymorphism and intersection types
Discriminator
discriminator.propertyName
Hint for code generators with 
oneOf
/
anyOf
Security
securitySchemes
+ top-level 
security
Bearer, API key, OAuth2, OpenID Connect
Tags
tags
on operations		Group operations for documentation
Type generation
openapi-typescript
Zero-runtime TypeScript types from spec
Typed fetch
openapi-fetch
Type-safe HTTP client using generated types
React Query
openapi-react-query
Type-safe React Query hooks from spec
Schema-first
zod-openapi
Generate OpenAPI documents from Zod schemas
模式元素核心要点
文档根节点
openapi
, 
info
, 
paths
顶层必须包含
openapi: '3.1.0'
路径项
/resources/{id}
路径参数使用大括号包裹
操作方法
get
, 
post
, 
put
, 
delete
, 
patch
每个操作需包含
operationId
和
responses
字段
参数
in: path|query|header|cookie
路径参数始终需要设置
required: true
请求体
requestBody.content
按媒体类型（如
application/json
）作为键值分类
响应
responses.200.content
每个操作至少需要定义一个响应
组件引用
$ref: '#/components/schemas/Name'
复用 Schema、参数、响应等组件
Schema 类型
type: string|number|integer|boolean|array|object
3.1 版本中数组支持
type: ["string", "null"]
格式
组合类型
oneOf
, 
anyOf
, 
allOf
实现多态模型和交叉类型
鉴别器
discriminator.propertyName
为使用
oneOf
/
anyOf
的代码生成器提供提示
安全机制
securitySchemes
+ 顶层
security
支持 Bearer、API Key、OAuth2、OpenID Connect 等方式
标签操作上的
tags
字段		为文档中的操作进行分组
类型生成
openapi-typescript
从规范生成零运行时的 TypeScript 类型
类型化请求
openapi-fetch
使用生成的类型创建类型安全的 HTTP 客户端
React Query 集成
openapi-react-query
从规范生成类型安全的 React Query 钩子
Schema 优先开发
zod-openapi
从 Zod Schema 生成 OpenAPI 文档

Common Mistakes

常见错误

MistakeCorrect Pattern
Using 
nullable: true
in 3.1		Use 
type: ["string", "null"]
(3.0 syntax removed)
Missing 
operationId
on operations		Always set unique 
operationId
for code generation
Path parameter not in 
required
Path parameters are always required (
required: true
)
Inline schemas everywhereExtract to 
components/schemas
and use 
$ref
allOf
with conflicting 
required
fields		Merge 
required
arrays; 
allOf
unions them
Discriminator without shared propertyAll schemas in 
oneOf
/
anyOf
must include the discriminator property
Empty 
description
on responses		Every response needs a meaningful 
description
Using 
type: object
without 
properties
Always define 
properties
or use 
additionalProperties
Circular 
$ref
chains		Break cycles with lazy resolution or restructure schemas
Mixing 3.0 and 3.1 syntaxChoose one version; 3.1 drops 
nullable
, changes 
exclusiveMinimum
to number
错误内容正确做法
在3.1版本中使用
nullable: true
使用
type: ["string", "null"]
（3.0版本语法已移除）
操作中缺失
operationId
字段		始终设置唯一的
operationId
以支持代码生成
路径参数未设置
required
路径参数始终需要设置
required: true
随处使用内联Schema提取到
components/schemas
并使用
$ref
引用
allOf
中包含冲突的
required
字段		合并
required
数组；
allOf
会自动合并这些数组
鉴别器未关联共享属性
oneOf
/
anyOf
中的所有Schema必须包含鉴别器指定的属性
响应中
description
为空		每个响应都需要设置有意义的
description
使用
type: object
但未定义
properties
始终定义
properties
或使用
additionalProperties
$ref
循环引用链		通过延迟解析或重构Schema来打破循环依赖
混合使用3.0和3.1版本语法选择单一版本；3.1版本移除了
nullable
，将
exclusiveMinimum
改为数字类型

Delegation

任务委托

  • API design review: Use 
    Task
    agent to audit spec completeness and consistency
  • Type generation: Use 
    Explore
    agent to find project-specific OpenAPI tooling config
  • Code review: Delegate to 
    code-reviewer
    agent for generated client usage patterns
If the 
typescript-patterns
skill is available, delegate advanced TypeScript typing questions to it.
  • API 设计评审：使用
    Task
    代理审核规范的完整性和一致性
  • 类型生成：使用
    Explore
    代理查找项目专属的 OpenAPI 工具配置
  • 代码评审：将生成的客户端使用模式相关问题委托给
    code-reviewer
    代理
若
typescript-patterns
技能可用，可将高级 TypeScript 类型相关问题委托给它处理。

References

参考资料

  • Schema design: paths, operations, parameters, components, and $ref
  • Data types: formats, composition, discriminators, and nullable
  • Code generation: openapi-typescript, openapi-fetch, openapi-react-query, and Zod OpenAPI
  • Documentation: Swagger UI, Redoc, and API docs best practices
  • Schema 设计：路径、操作、参数、组件与$ref
  • 数据类型：格式、组合、鉴别器与可空类型
  • 代码生成：openapi-typescript、openapi-fetch、openapi-react-query 与 Zod OpenAPI
  • 文档：Swagger UI、Redoc 与 API 文档最佳实践