@ahoo-wang/fetcher-openapi 2.1.1 → 2.2.2

package/README.md

@@ -13,10 +13,13 @@ ultra-lightweight HTTP client.
 
 ## Features
 
-- 📦 **Ultra-lightweight** - Minimal overhead TypeScript types only
-- 🦺 **Full TypeScript Support** - Complete type definitions for OpenAPI 3.x specification
-- 🧩 **Modular Design** - Import only what you need
+- 📦 **Ultra-lightweight** - Zero runtime overhead, TypeScript types only (~2KB)
+- 🦺 **Full TypeScript Support** - Complete type definitions for OpenAPI 3.0+ specification
+- 🧩 **Modular Design** - Import only what you need from specific modules
 - 🎯 **Framework Agnostic** - Works with any OpenAPI-compatible tooling
+- 🔧 **Extension Support** - Built-in support for OpenAPI extensions (x-\* properties)
+- 📚 **Comprehensive Coverage** - All OpenAPI 3.0+ features including schemas, parameters, responses, security, etc.
+- 🏗️ **Type-Safe Development** - Leverage TypeScript's type system for API development
 
 ## Installation
 
@@ -31,7 +34,12 @@ npm install @ahoo-wang/fetcher-openapi
 Import OpenAPI specification types:
 
 ```typescript
-import type { OpenAPI, Schema, Operation } from '@ahoo-wang/fetcher-openapi';
+import type {
+  OpenAPI,
+  Schema,
+  Operation,
+  Components,
+} from '@ahoo-wang/fetcher-openapi';
 
 const openAPI: OpenAPI = {
   openapi: '3.0.1',
@@ -43,6 +51,7 @@ const openAPI: OpenAPI = {
     '/users': {
       get: {
         summary: 'Get users',
+        operationId: 'getUsers',
         responses: {
           '200': {
             description: 'A list of users',
@@ -61,6 +70,85 @@ const openAPI: OpenAPI = {
       },
     },
   },
+  components: {
+    schemas: {
+      User: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          name: { type: 'string' },
+          email: { type: 'string', format: 'email' },
+        },
+        required: ['id', 'name'],
+      },
+    },
+  },
+};
+```
+
+### Working with Schemas
+
+Define complex data structures with full OpenAPI Schema support:
+
+```typescript
+import type { Schema, Discriminator, XML } from '@ahoo-wang/fetcher-openapi';
+
+const userSchema: Schema = {
+  type: 'object',
+  properties: {
+    id: { type: 'integer', minimum: 1 },
+    name: { type: 'string', minLength: 1, maxLength: 100 },
+    email: { type: 'string', format: 'email' },
+    role: { type: 'string', enum: ['admin', 'user', 'guest'] },
+    createdAt: { type: 'string', format: 'date-time' },
+  },
+  required: ['id', 'name', 'email'],
+};
+
+const polymorphicSchema: Schema = {
+  oneOf: [
+    { $ref: '#/components/schemas/Admin' },
+    { $ref: '#/components/schemas/User' },
+  ],
+  discriminator: {
+    propertyName: 'role',
+    mapping: {
+      admin: '#/components/schemas/Admin',
+      user: '#/components/schemas/User',
+    },
+  },
+};
+```
+
+### Extensions Support
+
+Use OpenAPI extensions for custom functionality:
+
+```typescript
+import type { Operation, CommonExtensions } from '@ahoo-wang/fetcher-openapi';
+
+const operationWithExtensions: Operation & CommonExtensions = {
+  summary: 'Get user profile',
+  operationId: 'getUserProfile',
+  'x-internal': false,
+  'x-deprecated': {
+    message: 'Use getUser instead',
+    since: '2.0.0',
+    removedIn: '3.0.0',
+    replacement: 'getUser',
+  },
+  'x-tags': ['users', 'profile'],
+  'x-order': 1,
+  responses: {
+    '200': {
+      description: 'User profile',
+      content: {
+        'application/json': {
+          schema: { $ref: '#/components/schemas/UserProfile' },
+        },
+      },
+    },
+  },
 };
 ```
 
@@ -68,24 +156,88 @@ const openAPI: OpenAPI = {
 
 ### Core Types
 
-- `OpenAPI` - Root document object
-- `Info` - API metadata
-- `Server` - Server configuration
-- `Paths` - API paths and operations
-- `Operation` - Single API operation
-- `Schema` - Data schema definition
-- `Parameter` - Operation parameter
-- `RequestBody` - Request body definition
-- `Response` - Response definition
-- `Components` - Reusable components
-- `SecurityScheme` - Security scheme definition
-
-### Utility Types
-
-- `ExtractSchemaType<S>` - Extract TypeScript type from OpenAPI Schema
-- `ExtractRequestBodyType<Op, Components>` - Extract request body type from Operation
-- `ExtractOkResponseBodyType<Op, Components>` - Extract successful response body type from Operation
-- `ResolveReference<R, Components>` - Resolve $ref references to actual types
+#### Document Structure
+
+- `OpenAPI` - Root OpenAPI document object
+- `Info` - API metadata (title, version, description, etc.)
+- `Contact` - Contact information for the API
+- `License` - License information
+- `Server` - Server configuration with variables
+- `Paths` - Collection of API paths and their operations
+- `Components` - Reusable components (schemas, parameters, responses, etc.)
+- `Tag` - API grouping and documentation tags
+
+#### Operations & Parameters
+
+- `Operation` - Single API operation (GET, POST, etc.)
+- `Parameter` - Operation parameter (query, path, header, cookie)
+- `RequestBody` - Request body definition with content types
+- `Response` - Response definition with status codes
+- `MediaType` - Content type definitions with schemas
+- `Encoding` - Serialization rules for request/response bodies
+
+#### Data Schemas
+
+- `Schema` - JSON Schema-based data structure definitions
+- `Discriminator` - Polymorphism support with discriminator fields
+- `XML` - XML serialization configuration
+- `Reference` - JSON Reference ($ref) for reusable components
+
+#### Security
+
+- `SecurityScheme` - Authentication scheme definitions
+- `SecurityRequirement` - Required security schemes for operations
+
+### Extensions & Utilities
+
+#### Extension Support
+
+- `Extensible` - Base interface for objects supporting extensions
+- `CommonExtensions` - Predefined extension properties (x-internal, x-deprecated, etc.)
+
+#### Type Utilities
+
+- `HTTPMethod` - Supported HTTP methods ('get', 'post', 'put', 'delete', etc.)
+- `ParameterLocation` - Parameter locations ('query', 'header', 'path', 'cookie')
+- `SchemaType` - JSON Schema primitive types ('string', 'number', 'boolean', etc.)
+
+### Advanced Usage
+
+#### Modular Imports
+
+Import only the types you need for better tree-shaking:
+
+```typescript
+// Import specific types
+import type { OpenAPI, Schema, Operation } from '@ahoo-wang/fetcher-openapi';
+
+// Or import from specific modules
+import type { OpenAPI } from '@ahoo-wang/fetcher-openapi/openAPI';
+import type { Schema } from '@ahoo-wang/fetcher-openapi/schema';
+import type { Operation } from '@ahoo-wang/fetcher-openapi/paths';
+```
+
+#### Type-Safe API Development
+
+Use these types to build type-safe API clients and documentation:
+
+```typescript
+function validateOpenAPI(doc: OpenAPI): boolean {
+  // TypeScript will catch type errors at compile time
+  return doc.openapi.startsWith('3.');
+}
+
+function createOperation(
+  path: string,
+  method: HTTPMethod,
+  config: Partial<Operation>,
+): Operation {
+  return {
+    operationId: `${method}${path.replace(/\//g, '')}`,
+    ...config,
+  };
+}
+```
 
 ## License
 

package/README.zh-CN.md

@@ -12,10 +12,13 @@
 
 ## 功能特性
 
-- 📦 **超轻量级** - 最小化开销的 TypeScript 类型定义
-- 🦺 **完整 TypeScript 支持** - OpenAPI 3.x 规范的完整类型定义
-- 🧩 **模块化设计** - 按需导入所需功能
+- 📦 **超轻量级** - 零运行时开销，仅 TypeScript 类型（~2KB）
+- 🦺 **完整 TypeScript 支持** - OpenAPI 3.0+ 规范的完整类型定义
+- 🧩 **模块化设计** - 从特定模块按需导入所需功能
 - 🎯 **框架无关** - 适用于任何与 OpenAPI 兼容的工具
+- 🔧 **扩展支持** - 内置支持 OpenAPI 扩展（x-\* 属性）
+- 📚 **全面覆盖** - 涵盖所有 OpenAPI 3.0+ 功能，包括模式、参数、响应、安全等
+- 🏗️ **类型安全开发** - 利用 TypeScript 类型系统进行 API 开发
 
 ## 安装
 
@@ -30,7 +33,12 @@ npm install @ahoo-wang/fetcher-openapi
 导入 OpenAPI 规范类型：
 
 ```typescript
-import type { OpenAPI, Schema, Operation } from '@ahoo-wang/fetcher-openapi';
+import type {
+  OpenAPI,
+  Schema,
+  Operation,
+  Components,
+} from '@ahoo-wang/fetcher-openapi';
 
 const openAPI: OpenAPI = {
   openapi: '3.0.1',
@@ -42,6 +50,7 @@ const openAPI: OpenAPI = {
     '/users': {
       get: {
         summary: '获取用户列表',
+        operationId: 'getUsers',
         responses: {
           '200': {
             description: '用户列表',
@@ -60,6 +69,85 @@ const openAPI: OpenAPI = {
       },
     },
   },
+  components: {
+    schemas: {
+      User: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          name: { type: 'string' },
+          email: { type: 'string', format: 'email' },
+        },
+        required: ['id', 'name'],
+      },
+    },
+  },
+};
+```
+
+### 使用模式
+
+使用完整的 OpenAPI Schema 支持定义复杂数据结构：
+
+```typescript
+import type { Schema, Discriminator, XML } from '@ahoo-wang/fetcher-openapi';
+
+const userSchema: Schema = {
+  type: 'object',
+  properties: {
+    id: { type: 'integer', minimum: 1 },
+    name: { type: 'string', minLength: 1, maxLength: 100 },
+    email: { type: 'string', format: 'email' },
+    role: { type: 'string', enum: ['admin', 'user', 'guest'] },
+    createdAt: { type: 'string', format: 'date-time' },
+  },
+  required: ['id', 'name', 'email'],
+};
+
+const polymorphicSchema: Schema = {
+  oneOf: [
+    { $ref: '#/components/schemas/Admin' },
+    { $ref: '#/components/schemas/User' },
+  ],
+  discriminator: {
+    propertyName: 'role',
+    mapping: {
+      admin: '#/components/schemas/Admin',
+      user: '#/components/schemas/User',
+    },
+  },
+};
+```
+
+### 扩展支持
+
+使用 OpenAPI 扩展实现自定义功能：
+
+```typescript
+import type { Operation, CommonExtensions } from '@ahoo-wang/fetcher-openapi';
+
+const operationWithExtensions: Operation & CommonExtensions = {
+  summary: '获取用户资料',
+  operationId: 'getUserProfile',
+  'x-internal': false,
+  'x-deprecated': {
+    message: '请使用 getUser 替代',
+    since: '2.0.0',
+    removedIn: '3.0.0',
+    replacement: 'getUser',
+  },
+  'x-tags': ['users', 'profile'],
+  'x-order': 1,
+  responses: {
+    '200': {
+      description: '用户资料',
+      content: {
+        'application/json': {
+          schema: { $ref: '#/components/schemas/UserProfile' },
+        },
+      },
+    },
+  },
 };
 ```
 
@@ -67,24 +155,88 @@ const openAPI: OpenAPI = {
 
 ### 核心类型
 
-- `OpenAPI` - 根文档对象
-- `Info` - API 元数据
-- `Server` - 服务器配置
-- `Paths` - API 路径和操作
-- `Operation` - 单个 API 操作
-- `Schema` - 数据模式定义
-- `Parameter` - 操作参数
-- `RequestBody` - 请求体定义
-- `Response` - 响应定义
-- `Components` - 可复用组件
-- `SecurityScheme` - 安全方案定义
-
-### 工具类型
-
-- `ExtractSchemaType<S>` - 从 OpenAPI Schema 中提取 TypeScript 类型
-- `ExtractRequestBodyType<Op, Components>` - 从 Operation 中提取请求体类型
-- `ExtractOkResponseBodyType<Op, Components>` - 从 Operation 中提取成功响应体类型
-- `ResolveReference<R, Components>` - 解析 $ref 引用为实际类型
+#### 文档结构
+
+- `OpenAPI` - OpenAPI 根文档对象
+- `Info` - API 元数据（标题、版本、描述等）
+- `Contact` - API 联系信息
+- `License` - 许可证信息
+- `Server` - 带变量的服务器配置
+- `Paths` - API 路径及其操作的集合
+- `Components` - 可复用组件（模式、参数、响应等）
+- `Tag` - API 分组和文档标签
+
+#### 操作和参数
+
+- `Operation` - 单个 API 操作（GET、POST 等）
+- `Parameter` - 操作参数（查询、路径、头部、cookie）
+- `RequestBody` - 带内容类型的请求体定义
+- `Response` - 带状态码的响应定义
+- `MediaType` - 带模式的媒体类型定义
+- `Encoding` - 请求/响应体的序列化规则
+
+#### 数据模式
+
+- `Schema` - 基于 JSON Schema 的数据结构定义
+- `Discriminator` - 带判别字段的多态支持
+- `XML` - XML 序列化配置
+- `Reference` - 可复用组件的 JSON 引用（$ref）
+
+#### 安全
+
+- `SecurityScheme` - 认证方案定义
+- `SecurityRequirement` - 操作所需的安全方案
+
+### 扩展和工具
+
+#### 扩展支持
+
+- `Extensible` - 支持扩展的对象基础接口
+- `CommonExtensions` - 预定义扩展属性（x-internal、x-deprecated 等）
+
+#### 类型工具
+
+- `HTTPMethod` - 支持的 HTTP 方法（'get'、'post'、'put'、'delete' 等）
+- `ParameterLocation` - 参数位置（'query'、'header'、'path'、'cookie'）
+- `SchemaType` - JSON Schema 原始类型（'string'、'number'、'boolean' 等）
+
+### 高级用法
+
+#### 模块化导入
+
+仅导入所需的类型以实现更好的树摇优化：
+
+```typescript
+// 导入特定类型
+import type { OpenAPI, Schema, Operation } from '@ahoo-wang/fetcher-openapi';
+
+// 或从特定模块导入
+import type { OpenAPI } from '@ahoo-wang/fetcher-openapi/openAPI';
+import type { Schema } from '@ahoo-wang/fetcher-openapi/schema';
+import type { Operation } from '@ahoo-wang/fetcher-openapi/paths';
+```
+
+#### 类型安全 API 开发
+
+使用这些类型构建类型安全的 API 客户端和文档：
+
+```typescript
+function validateOpenAPI(doc: OpenAPI): boolean {
+  // TypeScript 会在编译时捕获类型错误
+  return doc.openapi.startsWith('3.');
+}
+
+function createOperation(
+  path: string,
+  method: HTTPMethod,
+  config: Partial<Operation>,
+): Operation {
+  return {
+    operationId: `${method}${path.replace(/\//g, '')}`,
+    ...config,
+  };
+}
+```
 
 ## 许可证
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahoo-wang/fetcher-openapi",
-  "version": "2.1.1",
+  "version": "2.2.2",
   "description": "OpenAPI Specification TypeScript types for Fetcher - A modern, ultra-lightweight HTTP client for browsers and Node.js. Provides complete TypeScript support with type inference for OpenAPI 3.x schemas.",
   "keywords": [
     "fetch",