openapi-schema-type

v1.0.0

Published

18 days ago

OpenAPI Schema object type definition

0High
0Medium
0Low

kevinwon

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 类型提示和文档注释

安装

npm install openapi-schema-type

使用方法

基本用法

安装包后，使用 ES6 模块语法导入需要的类型：

// 导入需要的类型
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
};

使用引用对象

// 使用 $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: "引用用户模式定义"
};

高级示例

// 导入多个类型
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，但排除了布尔值模式。

import { SchemaObject } from "openapi-schema-type";

type SchemaObject = Exclude<JSONSchemaMeta202012, boolean>;

`ReferenceObject`

用于引用其他组件的引用对象类型。

import { ReferenceObject } from "openapi-schema-type";

interface ReferenceObject {
  $ref: string;
  summary?: string;
  description?: string;
}

`SpecificationExtensionKey` 和 `SpecificationExtensions`

OpenAPI 扩展字段的类型定义。

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+

许可证

ISC

贡献

欢迎提交 Issue 和 Pull Request！

仓库

https://github.com/ww-k/openapi-schema-type

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme