OpenAPI-TS 中默认值参数的类型生成问题解析

在 TypeScript 生态中，openapi-typescript 是一个广泛使用的工具，它能够将 OpenAPI 规范转换为 TypeScript 类型定义。然而，在实际使用过程中，开发者可能会遇到一个常见问题：当 OpenAPI 规范中定义了带有默认值的参数时，生成的 TypeScript 类型并不会自动将这些参数标记为可选。

问题背景

在 OpenAPI 规范中，我们可以为参数或属性指定默认值。这意味着如果客户端在请求中未提供该参数，服务器将使用预设的默认值。从逻辑上讲，这类参数应该被视为可选参数，因为客户端可以选择不提供它们。

然而，openapi-typescript 在默认配置下（从某个版本开始）会将所有带有默认值的参数视为必填项（required），除非显式地通过 --default-non-nullable=false 标志禁用这一行为。这与许多开发者的直觉预期相悖。

技术细节分析

让我们通过一个具体的 OpenAPI 规范示例来说明这个问题：

components:
  schemas:
    HuntingSkill:
      type: object
      properties:
        huntingSkill:
          type: string
          default: lazy
          enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
      required: []

在这个例子中，huntingSkill 属性有一个默认值 "lazy"，而且它没有被包含在 required 列表中。按照 OpenAPI 的语义，这意味着：

1. 客户端可以省略这个参数
2. 如果省略，服务器将使用 "lazy" 作为默认值

然而，openapi-typescript 默认会生成以下类型定义：

readonly HuntingSkill: {
    readonly huntingSkill: IntApiHuntingSkillHuntingSkillEnum;
};

而不是开发者预期的：

readonly HuntingSkill: {
    readonly huntingSkill?: IntApiHuntingSkillHuntingSkillEnum;
};

解决方案

要解决这个问题，开发者有以下几种选择：

1. 使用 CLI 标志：在生成类型定义时添加 --default-non-nullable=false 标志

   openapi-typescript schema.yaml -o types.ts --default-non-nullable=false
   

2. 修改 OpenAPI 规范：如果可能，在规范中显式地将这些参数标记为 required: false

3. 手动修改生成的类型：虽然不推荐，但在某些情况下可以作为临时解决方案

最佳实践建议

1. 明确设计意图：在编写 OpenAPI 规范时，应该清楚地表达每个参数的必需性。即使有默认值，也要考虑是否真的希望客户端能够省略该参数。

2. 团队一致性：在团队中建立统一的约定，决定如何处理带有默认值的参数，以避免不同成员之间的理解差异。

3. 文档说明：在项目的 README 或文档中明确说明类型生成的行为，特别是关于默认值参数的处理方式。

深入理解

这种行为变化实际上是 openapi-typescript 的一个有意设计。在某些情况下，服务器端可能希望确保某些参数总是有值（即使是通过默认值提供的），因此将这些参数视为必填项可能更符合实际需求。

开发者需要理解的是，OpenAPI 规范中的 default 和 required 是两个独立的概念：

• default 指定了当值缺失时应该使用的值
• required 决定了客户端是否可以省略该值

openapi-typescript 的默认行为实际上是将 default 视为一种隐式的 required，这虽然与某些开发者的直觉相悖，但在某些场景下可能更有意义。

结论

理解 openapi-typescript 如何处理带有默认值的参数对于构建健壮的 API 客户端至关重要。开发者应该根据自己项目的实际需求，选择适当的配置方式，确保生成的类型定义与 API 的实际行为保持一致。通过明确的设计决策和团队共识，可以避免这类问题对开发流程造成影响。