NSwag：生成 C# 客户端导致代码无效

如何解决NSwag：生成 C# 客户端导致代码无效

我正在尝试为 Trello API 生成 C# 客户端。因此，我从 https://developer.atlassian.com/cloud/trello/swagger.v3.json 下载了 Open API 规范，并从 bash 运行以下 nswag 命令。

nswag openapi2csclient /input:swagger.v3.json \
    /classname:TrelloClient \
    /namespace:Integrations.Trello \
    /output:TrelloClient.cs \
    /GenerateClientInterfaces:True \
    /GenerateExceptionClasses:True \
    /GenerateClientClasses:True \
    /disposeHttpClient:False \
    /OperationGenerationMode:SingleClientFromOperationId

代码生成完成没有错误，但生成的代码没有编译，因为它包含很多错误。例如，某些生成的方法名称包含无效的表达式，例如 =idAsync，或者方法签名具有不明确的参数（例如，类型为 key 的多个 token 和 string 参数） .为 GetMembers 方法生成了以下方法声明，这显然是错误的语法。

System.Threading.Tasks.Task<Member> GetMembers=idAsync(
    string key,string token,string id,string actions,string boards,BoardBackgrounds? boardBackgrounds,BoardsInvited? boardsInvited,BoardFields? boardsInvited_fields,bool? boardStars,string cards,CustomBoardBackgrounds? customBoardBackgrounds,CustomEmoji2? customEmoji,CustomStickers? customStickers,MemberFields? fields,string notifications,Organizations? organizations,OrganizationFields? organization_fields,bool? organization_paid_account,OrganizationsInvited? organizationsInvited,OrganizationFields? organizationsInvited_fields,bool? paid_account,bool? savedSearches,Tokens? tokens);

在处理版本3的Open API规范文档时，有没有需要设置的特殊选项？

解决方法

通过将 get-members 从 OperationGenerationMode 更改为 SingleClientFromOperationId，我能够解决有关生成代码中 SingleClientFromPathSegments 方法的语法问题。这是一种解决方法，因为 =id 术语仅出现在 operationId 中。

我检查了 Trello 的 Open API 规范文档，发现 get-members 的定义在 =id 中包含 operationId 术语；不确定这是否在规范中是错误的，或者生成器无法正确处理这种情况。 get-members 方法的定义如下所示（缩短）：

... "/members/{id}":
{
   "get":
   {
       "tags": [],"operationId":"get-members=id","parameters" ...
   }
}

作为旁注，我使用 SingleClient... 操作模式的原因是 Nswag 还向任何部分类和接口添加了 GeneratedCode 属性，这也会导致无效代码（此属性只能申请一次）。 SingleClient... 操作模式解决了这个问题。

剩下的就是NSwag生成参数重复的方法的问题，已经被报告为问题，但尚未解决；有关详细信息，请参阅 https://github.com/RicoSuter/NSwag/issues/2560。最后但并非最不重要的是，我尝试从 =id 中删除 operationId 并切换回 SingleClientFromOperationId 操作模式以检查这是否有效，但事实并非如此。>

我假设 NSwag 被广泛的受众使用，这让我认为这与处理后的规范的相关性高于 Nswag。因此，我查找了 C# 编译器报告为具有重复参数的方法的规范。这是一个例子。

...
{
    "name": "token","in": "query","description": "The API token to use","required": true,"schema": {
        "$ref": "#/components/schemas/APIToken"
    }
},{
    "name": "token","in": "path","description": "","schema": {
        "type": "string"
    }
}
...

所以看起来一个方法可以有同名的参数，但它们可以出现在不同的地方，比如查询字符串，或者是 URL 路径的一部分。那么，可能是 Nswag 产生了错误的输出；如果打算将这两个参数都发送到 API，那么生成器应该只在名称前加上前缀以避免歧义，例如 queryToken 和 pathToken，让开发人员来决定什么使用或提示预期值的参数（以防两个参数都是必需的并且期望不同的值）。