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

【问题标题】：NSwag: Generation of a C# client results in invalid codeNSwag：生成 C# 客户端会导致代码无效
【发布时间】：2021-07-27 03:56:27
【问题描述】：

我正在尝试为 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规范文档时，有什么特殊的选项需要设置吗？

【问题讨论】：

标签： c# .net-core trello openapi-generator nswag

【解决方案1】：

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

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

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

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

剩下的就是NSwag生成方法参数重复的问题，这个问题已经被报告为问题，但还没有解决；请参阅https://github.com/RicoSuter/NSwag/issues/2560 了解更多信息。最后但同样重要的是，我尝试从operationId 中删除=id 并切换回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": "",
    "required": true,
    "schema": {
        "type": "string"
    }
}
...

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

【讨论】：