NSwagStudio 和 Swagger 2.0 x-sub_types答案

【问题标题】：NSwagStudio and Swagger 2.0 x-sub_typesNSwagStudio 和 Swagger 2.0 x-sub_types
【发布时间】：2020-10-18 05:25:40
【问题描述】：

我认为这是一个 NSwag 或 NSwagStudio 问题，但我没有足够的经验知道我是否使用错误，或者 NSwag 中是否存在错误或我的 Swagger 2.0 文档有问题消费。

我正在使用 NSwagStudio 13.6.1.0 为 Salesforce OCAPI Shop API 生成 C# 客户端。表示order_search_request 属性query 的类型作为没有属性的空类出现。但是 Swagger 文档声明了 query 的几个子类型，其中一些确实具有属性：

  "query": {
      "$ref": "#/definitions/query",
      "description": "The query to apply",
      "x-sub_types": {
          "nested_query": "#/definitions/nested_query",
          "filtered_query": "#/definitions/filtered_query",
          "text_query": "#/definitions/text_query",
          "match_all_query": "#/definitions/match_all_query",
          "term_query": "#/definitions/term_query",
          "bool_query": "#/definitions/bool_query"
      }
  }

起初我假设这些x-sub_types 应该作为Query 的子类生成，但事实并非如此。但根据请求正文应该包含的内容的非 Swagger 文档，Query 似乎应该拥有这些子类型之一，而不是成为一个其中：

{ 
   "query" :
   { 
      "text_query": { "fields": ["customer_email"], "search_phrase":"example@non.existing.com" }
   },
   "select" : "(**)",
   "sorts" : [{"field":"customer_name", "sort_order":"asc"}]
}

由于 NSwag 生成部分类，我也许可以自己将必要的字段添加到 Query。但这真的是最好的解决方案吗？我想知道是否有可能让 NSwag 首先做正确的事情，或者 Swagger 文档是否错误地描述了 API。另一个明显的可能性，特别是考虑到 x- 前缀，是 x-sub_types 只是 Salesforce 发明的一些非标准的东西。

【问题讨论】：

标签： c# nswag nswagstudio

【解决方案1】：

对于它的价值，手动将“子类型”属性添加到我自己生成的Query 类的部分按预期工作。不过，我仍然不知道这是否是“答案”。可能有一种方法可以自定义 NSwag 来处理这个问题。（SalesforceServices.OCAPI.Shop是我给生成客户端的包名。）

using Newtonsoft.Json;

namespace SalesforceServices.OCAPI.Shop
{
    public partial class Query
    {
        [JsonProperty("text_query", NullValueHandling = NullValueHandling.Ignore)]
        public Text_query TextQuery { get; set; }
        [JsonProperty("match_all_query", NullValueHandling = NullValueHandling.Ignore)]
        public Match_all_query MatchAllQuery { get; set; }
        // TODO all the query types!
    }
}

【讨论】：