NSwagStudio and Swagger 2.0 x-sub_types

Question

I think this is a NSwag or NSwagStudio question, but I'm not experienced enough with it to know if I'm using it wrong, or if there's a bug in NSwag or a problem with the Swagger 2.0 document I'm consuming.

I'm using NSwagStudio 13.6.1.0 to generate a C# client for the Salesforce OCAPI Shop API. The type representing the order_search_request property query comes out as an empty class with no properties. But the Swagger doc declares several subtypes of query, some of which do have properties:

  "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"
      }
  }

At first I assumed that these x-sub_types were supposed to be generated as subclasses of Query, which they aren't. But based on the non-Swagger docs for what the request body is supposed to contain, it appears that Query is supposed to have one of these subtypes, not be one of them:

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

Since NSwag generates partial classes, I might be able to add the necessary fields to Query myself. But is that really the best solution? I'd like to know if it's possible to make NSwag do the right thing in the first place, or if the Swagger doc describes the API incorrectly. Another distinct possibility, especially considering the x- prefix, is that x-sub_types is just some non-standard thing that Salesforce invented.

score 0 · Answer 1 · answered Jun 27 '20 at 23:26

For what it's worth, manually adding the "subtype" properties to my own partial of the generated Query class works as expected. I still don't know if this is "the" answer, though. There might be a way to customize NSwag to handle this. (SalesforceServices.OCAPI.Shop is the package name I gave the generated client.)

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!
    }
}

NSwagStudio and Swagger 2.0 x-sub_types

1 Answers1