Cómo mostrar el ‘discriminador’ en la documentación generada por Nswag?
Hemos desarrollado una API y utilizado la herramienta Nswag para generar automáticamente la documentación de la API Swagger. Tenemos algunos puntos finales en nuestra API, donde queremos actualizar algunos campos utilizando la herencia. Para una explicación más detallada, tenemos un método de actualización (como POST api/person/{id}) donde el usuario proporciona un JSON en el cuerpo y al proporcionar el discriminador, el programa conoce el tipo, puede deserializar la cadena JSON y utilizar el método de actualización correcto, como UpdateAddress o algo similar. Cuando el usuario no proporciona esta información, entonces el objeto deserializado en nuestro cliente es nulo y produce errores.
Ahora hay un problema, que la documentación Swagger generada no muestra la propiedad del discriminador. Visualiza correctamente la estructura de herencia con las propiedades utilizando este enfoque:
[JsonConverter(typeof(JsonInheritanceConverter), "discriminator")]
[KnownType(typeof(PersonUpdateAddressCommand))]
public class PersonCommand : CommandBase
{
}
El usuario no sabe que tiene que proporcionar la propiedad del discriminador, hasta que se lo decimos, pero la documentación debería ser autoexplicativa en el mejor de los casos.
Para resolver esto, agregué una propiedad pública de tipo string en la clase CommandBase con el nombre de ‘discriminator’:
public abstract class CommandBase
{
public string discriminator { get; set; }
}
Ahora se visualizaría la propiedad en la documentación, pero esto parece un poco excesivo, porque este ‘property’ del discriminador ya existe en algún lugar en el montón de datos, entonces, ¿por qué definir una propiedad adicional?
¿Hay alguna manera de mostrar el discriminador en la documentación de Swagger generada sin definir una propiedad adicional? ¿O es este el enfoque correcto para agregar una propiedad de tipo string?
davy.ai
Como experto en IT especializado en C#, API, Swagger y Nswag, has implementado herencia en tu API y has utilizado Nswag para generar automáticamente la documentación de la API de Swagger. Sin embargo, te has encontrado con un problema en el que la propiedad de discriminador no es visible en la documentación de Swagger, lo cual puede causar confusión a los usuarios, ya que pueden no saber que esta propiedad debe ser proporcionada.
Para solucionar este problema, has considerado agregar una propiedad de tipo string pública a la clase CommandBase con el nombre de “discriminator” para hacerla visible en la documentación de Swagger. Sin embargo, no estás seguro si esta es la mejor opción, ya que la propiedad de discriminador ya existe en el montón.
Desafortunadamente, no hay una forma directa de mostrar la propiedad de discriminador en la documentación de Swagger sin agregar una propiedad adicional a la clase base. La opción que has considerado de agregar una propiedad de tipo string con el nombre de “discriminator” a la clase CommandBase es la forma correcta de resolver este problema.
Si bien esta opción puede parecer excesiva, ya que la propiedad de discriminador ya existe en el montón, garantiza que la documentación de Swagger sea autoexplicativa para los usuarios. Sin esta propiedad adicional, los usuarios pueden no saber que necesitan proporcionar la propiedad de discriminador en la carga JSON, lo que puede llevar a errores y confusión.
Por lo tanto, agregar una propiedad de tipo string con el nombre de “discriminator” a la clase CommandBase es la forma más adecuada de mostrar el discriminador en la documentación de Swagger generada, al tiempo que se asegura de que la API sea fácil de usar y amigable para los usuarios.