0

we have developed an api and used the tool Nswag to automatically generate the Swagger api documentation. We have some endpoints in our api, where we want to update some fields by using inheritance. For nearer explanation, we have one update method (like POST api/person/{id}) where the user provide a json in the body and by giving the discriminator, the program knows the type, can deserialize the json string and use the right update method, like UpdateAddress or something. When the user does not give this information, then the deserialized object in our client is null and results in errors.

Now there is a problem, that the generated Swagger documentation does not show the discriminator 'property'. It rightly visualizes the inheritance structure with the properties by using this approach:

[JsonConverter(typeof(JsonInheritanceConverter), "discriminator")]
[KnownType(typeof(PersonUpdateAddressCommand))]
public class PersonCommand : CommandBase
{
}

The user does not know, that he have to provide the discriminator property, until we say this to him, but the documentation should be self-explanatory in best case.

To solve this, I added a public string property in the CommandBase class with the name 'discriminator':

public abstract class CommandBase
{
  public string discriminator { get; set; }
}

Now it would visualize the property in the documentation, but this seems a bit over the top, because this discriminator 'property' is already existing somewhere in the heap, so why define an extra property?

Is there a way, to show the discriminator in the generated swagger documentation without defining an extra property? Or is this the right approach to add a string property?

Vorticity1848
  • 1
  • 1
  • I don't know the answer, but I do know that NSwag, being open source, is something you can read the code of and find the relevant place where you'd like the discriminator to be output and add it in if you can't find any support for it already... – Caius Jard Jan 04 '22 at 08:21

1 Answers1

0

The underlying library NJsonschema does not support system.text.json yet hence it doesn't work unless you use json.net as your serializer

Zyo
  • 1
  • 1
    Your answer could be improved with additional supporting information. Please [edit] to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers [in the help center](/help/how-to-answer). – Community Feb 24 '22 at 22:43