openapi-schema-type 1.0.0

package/README.md

@@ -0,0 +1,246 @@
+# OpenAPI Schema Type
+
+OpenAPI Schema 对象的 TypeScript 类型定义。
+
+## 简介
+
+本项目提供了 OpenAPI 3.2 和 3.1 规范中 Schema 对象的完整 TypeScript 类型定义。它基于 JSON Schema 2020-12 规范，特别针对 OpenAPI 的使用场景进行了优化，提供了类型安全的方式来定义和使用 OpenAPI Schema。
+
+## 特性
+
+- ✅ 完整的 OpenAPI 3.2 和 3.1 Schema 对象支持
+- ✅ 基于 JSON Schema 2020-12 规范
+- ✅ 包含所有官方词汇表：
+  - **Core**: 核心标识和引用机制（`$id`, `$ref`, `$schema` 等）
+  - **Applicator**: 应用器，定义如何应用子模式（`properties`, `items`, `allOf` 等）
+  - **Unevaluated**: 处理未求值位置（`unevaluatedItems`, `unevaluatedProperties`）
+  - **Validation**: 验证约束（`type`, `minimum`, `maxLength` 等）
+  - **Meta-Data**: 元数据注解（`title`, `description`, `examples` 等）
+  - **Format**: 格式注解（`format`）
+  - **Content**: 内容编码（`contentEncoding`, `contentMediaType` 等）
+- ✅ 排除布尔值模式以符合 OpenAPI 规范
+- ✅ 支持 OpenAPI 特有的扩展字段（`x-*`）
+- ✅ 支持引用对象（`ReferenceObject`）
+- ✅ 完整的 TypeScript 类型提示和文档注释
+
+## 安装
+
+```bash
+npm install openapi-schema-type
+```
+
+## 使用方法
+
+### 基本用法
+
+安装包后，使用 ES6 模块语法导入需要的类型：
+
+```typescript
+// 导入需要的类型
+import { InfoObject, SchemaObject, ReferenceObject, ComponentsObject } from "openapi-schema-type";
+
+// OpenAPI Schema 对象定义
+const userSchema: SchemaObject = {
+  title: "User",
+  description: "用户信息模式",
+  type: "object",
+  properties: {
+    name: {
+      type: "string",
+      minLength: 1,
+      maxLength: 100
+    },
+    age: {
+      type: "integer",
+      minimum: 0,
+      maximum: 150
+    },
+    email: {
+      type: "string",
+      format: "email"
+    }
+  },
+  required: ["name", "email"],
+  additionalProperties: false
+};
+```
+
+### 使用引用对象
+
+```typescript
+// 使用 $ref 引用
+import { SchemaObject, ReferenceObject } from "openapi-schema-type";
+
+const addressSchema: SchemaObject | ReferenceObject = {
+  $ref: "#/components/schemas/Address"
+};
+
+// 带有额外信息的引用对象
+const detailedRef: ReferenceObject = {
+  $ref: "#/components/schemas/User",
+  summary: "用户引用",
+  description: "引用用户模式定义"
+};
+```
+
+### 高级示例
+
+```typescript
+// 导入多个类型
+import { SchemaObject, ComponentsObject, InfoObject } from "openapi-schema-type";
+
+// 使用组合关键字
+const polymorphicSchema: SchemaObject = {
+  oneOf: [
+    { type: "string" },
+    { type: "number" },
+    {
+      type: "object",
+      properties: {
+        value: { type: "string" }
+      }
+    }
+  ]
+};
+
+// 使用扩展字段
+const extendedSchema: SchemaObject = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    "x-internal-id": {
+      type: "string",
+      description: "内部使用的标识符"
+    }
+  }
+};
+
+// 完整的组件定义示例
+const components: ComponentsObject = {
+  schemas: {
+    User: {
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" },
+        name: { type: "string" },
+        email: { type: "string", format: "email" },
+        createdAt: { type: "string", format: "date-time" }
+      },
+      required: ["id", "name", "email"]
+    },
+    Address: {
+      type: "object",
+      properties: {
+        street: { type: "string" },
+        city: { type: "string" },
+        country: { type: "string" },
+        postalCode: { type: "string" }
+      },
+      required: ["street", "city", "country"]
+    }
+  }
+};
+```
+
+## API 文档
+
+### 主要类型
+
+包直接导出所有 OpenAPI 类型定义，无需使用命名空间：
+
+#### `SchemaObject`
+
+OpenAPI 规范中的 Schema 对象类型，基于 JSON Schema 2020-12，但排除了布尔值模式。
+
+```typescript
+import { SchemaObject } from "openapi-schema-type";
+
+type SchemaObject = Exclude<JSONSchemaMeta202012, boolean>;
+```
+
+#### `ReferenceObject`
+
+用于引用其他组件的引用对象类型。
+
+```typescript
+import { ReferenceObject } from "openapi-schema-type";
+
+interface ReferenceObject {
+  $ref: string;
+  summary?: string;
+  description?: string;
+}
+```
+
+#### `SpecificationExtensionKey` 和 `SpecificationExtensions`
+
+OpenAPI 扩展字段的类型定义。
+
+```typescript
+import { SpecificationExtensionKey, SpecificationExtensions } from "openapi-schema-type";
+
+type SpecificationExtensionKey = `x-${string}`;
+type SpecificationExtensions = Record<SpecificationExtensionKey, unknown>;
+```
+
+### 导出的类型
+
+安装包后，可以通过 ES6 模块导入以下类型：
+
+- `SchemaObject`: Schema 对象类型
+- `ReferenceObject`: 引用对象类型
+- `InfoObject`: Info 对象类型
+- `ComponentsObject`: Components 对象类型
+- `PathsObject`: Paths 对象类型
+- `OperationObject`: Operation 对象类型
+- `ParameterObject`: Parameter 对象类型
+- `RequestBodyObject`: RequestBody 对象类型
+- `ResponseObject`: Response 对象类型
+- `ResponsesObject`: Responses 对象类型
+- `MediaTypeObject`: MediaType 对象类型
+- `EncodingObject`: Encoding 对象类型
+- `ExampleObject`: Example 对象类型
+- `LinkObject`: Link 对象类型
+- `HeaderObject`: Header 对象类型
+- `SecuritySchemeObject`: SecurityScheme 对象类型
+- `SecurityRequirementObject`: SecurityRequirement 对象类型
+- `TagObject`: Tag 对象类型
+- `ExternalDocumentationObject`: ExternalDocumentation 对象类型
+- `ServerObject`: Server 对象类型
+- `ServerVariableObject`: ServerVariable 对象类型
+- `CallbacksObject`: Callbacks 对象类型
+- `SpecificationExtensions`: OpenAPI 扩展字段类型
+- `MapOfString`: 字符串映射类型
+- `OpenAPIDocument`: 完整的 OpenAPI 文档类型
+
+## 版本支持
+
+本项目支持以下 OpenAPI 规范版本：
+
+- ✅ **OpenAPI 3.2** (基于 2025-09-17 的 schema)
+- ✅ **OpenAPI 3.1** (基于 2025-09-15 的 schema)
+
+## 兼容性
+
+- TypeScript 4.5+
+- Node.js 14+
+
+## 相关资源
+
+- [OpenAPI 官方网站](https://www.openapis.org/)
+- [OpenAPI 3.2 规范](https://spec.openapis.org/oas/v3.2.0)
+- [OpenAPI 3.1 规范](https://spec.openapis.org/oas/v3.1.0)
+- [JSON Schema 官方网站](https://json-schema.org/)
+- [JSON Schema 2020-12 规范](https://json-schema.org/draft/2020-12/)
+
+## 许可证
+
+ISC
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 仓库
+
+[https://github.com/ww-k/openapi-schema-type](https://github.com/ww-k/openapi-schema-type)

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./typings/openapi_spec_3.2_schema.d";

package/index.js

@@ -0,0 +1 @@
+throw new Error("No js, just typescript type");

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "openapi-schema-type",
+    "description": "OpenAPI Schema object type definition",
+    "version": "1.0.0",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ww-k/openapi-schema-type.git"
+    },
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "import": "./index.js",
+            "require": "./index.js"
+        },
+        "./typings": "./typings/*.d.ts"
+    },
+    "main": "./index.js",
+    "types": "./index.d.ts",
+    "type": "module",
+    "files": [
+        "index.js",
+        "index.d.ts",
+        "typings"
+    ],
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "license": "ISC",
+    "dependencies": {
+        "json-schema-meta-type": "^1.0.0"
+    }
+}