NSwag生成Adobe Sign API客户端时可选参数处理异常求助

问题梳理 #

你基于Adobe Sign的Swagger 1.2转换而来的OpenAPI 3.0.1定义生成C#客户端时，遇到以下核心问题：

• 可选的File-Name和Mime-Type参数生成后方法签名带null默认值，但代码内部会因值为null抛出异常
• 必填的File参数也被生成带null默认值，不符合必填参数的预期
• 尝试设置generateOptionalParameters: false导致所有参数变为必填，不符合需求

解决方案 #

1. 修正OpenAPI定义的参数标记 #

首先确保转换后的OpenAPI 3.0.1文件里，参数的必填性和可空性标记正确——这是生成正确代码的基础：

• 给必填的File参数明确添加required: true
• 给可选的File-Name、Mime-Type添加required: false和nullable: true

示例修正后的OpenAPI片段：

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        required:
          - File
        properties:
          File:
            type: string
            format: binary
          File-Name:
            type: string
            nullable: true
          Mime-Type:
            type: string
            nullable: true

2. 配置OpenAPI Generator的C#专属参数 #

放弃generateOptionalParameters: false，改用以下两个针对性配置：

• requiredParametersAsNonNullable: true：让必填参数生成非可空类型，方法签名无默认值
• optionalParameterStyle: nullableReferenceTypes：让可选参数生成C#可空引用类型（带?），且内部不会强制非空检查（需C# 8+及对应目标框架）

示例配置（以openapi-generator-cli的config.json为例）：

{
  "generatorName": "csharp",
  "inputSpec": "path/to/adobe-sign-transient.yaml",
  "output": "./generated-client",
  "configOptions": {
    "requiredParametersAsNonNullable": true,
    "optionalParameterStyle": "nullableReferenceTypes",
    "targetFramework": "net6.0"
  }
}

3. 手动修正生成代码（临时应急方案） #

如果上述配置仍未解决问题，可直接修改生成的客户端代码：

• 找到处理File-Name和Mime-Type的方法，移除参数的非空检查代码（比如if (fileName == null) throw new ArgumentNullException(nameof(fileName));）
• 将必填的File参数的方法签名从Stream? File = null改为Stream File，移除默认值并设为非可空

4. 验证OpenAPI转换准确性 #

检查Swagger 1.2转OpenAPI 3.0.1的过程是否丢失了参数属性：

• 用Swagger Editor打开转换后的文件，逐一确认File的required标记、File-Name/Mime-Type的nullable标记是否正确

内容的提问来源于stack exchange，提问作者Dustin Luck