导入TypeScript文件为何会破坏OpenAPI类型检查？

问题场景 #

我有一个仅导出OpenAPI对象Schema常量的TypeScript文件：

export default {
  "title": "Draft",
  "description": "A new draft listing",
  "type": "object",
  "additionalProperties": false,
  "required": ["id"],
  "properties": {
    "id": {"type": "string"}
  }
}

尝试将该Schema导入到另一个文件的OpenAPI文档中作为组件：

import Draft from './__generated_schemas__/draft.js'
import { OpenAPIV3 } from 'openapi-types'

export const schema: OpenAPIV3.Document = {
  openapi: '3.1',
  info: {
    title: 'Properties API',
    version: '1.0.0',
    description: 'Nice service description'
  },
  components: {schemas: {Draft}},
  paths: {}
}

报错信息 #

此时TypeScript抛出类型错误：

packages/api/src/schema.ts(22,7): error TS2322: Type '{ title: string; ... }' is not assignable to type 'ReferenceObject | SchemaObject'.
  ... 类型不兼容：Type 'string' is not assignable to type 'NonArraySchemaObjectType | undefined'.

但直接将该JSON内容复制粘贴到OpenAPI Schema中时，完全正常运行。

原因分析 #

问题核心在于TypeScript的类型推断逻辑差异：

• 直接写入时的上下文推断：当你把Schema内容直接写在OpenAPIV3.Document对象内部时，TypeScript会利用上下文类型推断，自动将type: "object"识别为NonArraySchemaObjectType类型的字面量（即具体的"object"字符串，而非宽泛的string类型），完美匹配openapi-types的类型约束。
• 单独导出时的宽泛推断：当你在单独文件导出这个对象时，TypeScript没有了OpenAPIV3.Document的上下文约束，会把type字段的类型推断为宽泛的string类型。而openapi-types定义的SchemaObject要求type必须是"object"/"string"/"number"等特定字面量的联合类型，宽泛的string无法匹配该联合类型，因此触发类型不兼容报错。

简单来说，单独导出的对象失去了目标类型的上下文约束，导致TypeScript推断出的类型过于宽泛，不符合openapi-types的严格类型定义。

内容的提问来源于stack exchange，提问作者Daniel Gruszczyk