Valores de ejemplo (espacios reservados) para los parámetros de consulta en Swagger (Swashbuckle).

Estoy utilizando Swashbuckle en .NET Core para crear una API documentada con Swagger.

La función que tengo utiliza parámetros de consulta. Quería agregar una breve descripción para cada parámetro de consulta, al lado de la casilla de texto donde se ingresa el valor del parámetro. Logré esto utilizando comentarios XML:

/// <param name="propertyId">El ID de la propiedad de integración. Se devolverán eventos relacionados con presentaciones relacionadas con este ID public ActionResult GetEvents([BindRequired] string propertyId){}

Esto funciona bien, pero también agrega el texto de descripción en el marcador de posición del cuadro de texto:

Vi que se puede cambiar el marcador de posición si el JSON generado tiene un valor de ‘ejemplo’ para el parámetro de consulta. ¿Cómo puedo agregar el valor de ejemplo o cambiar el marcador de posición en general utilizando los comentarios XML o algo similar?

davy.ai

July 21, 2023 at 9:56 pm

Para cambiar el marcador de posición de un parámetro de consulta en Swashbuckle utilizando comentarios XML, puedes agregar un valor de ejemplo en tu comentario XML usando el siguiente formato:

/// <param name="nombreDelParametro" example="valorEjemplo">Descripción del parámetro

Por ejemplo, para cambiar el marcador de posición del parámetro “propertyId”, puedes modificar tu código de la siguiente manera:

/// <param name="propertyId" example="123">El ID de propiedad de integración. Se devolverán los eventos relacionados con las presentaciones relacionadas con este ID
public ActionResult GetEvents([BindRequired] string propertyId){}

Esto establecerá el marcador de posición del cuadro de texto del parámetro en “123”. Puedes reemplazar “123” con el valor de ejemplo que desees utilizar.

Alternativamente, puedes utilizar el atributo OpenApiParameter de Swashbuckle para personalizar la descripción del parámetro y el valor de ejemplo. Aquí tienes un ejemplo:

[HttpGet]
[OpenApiOperation("GetEvents", "Obtener eventos por ID de propiedad")]
public ActionResult<><event>> GetEvents(
    [BindRequired]
    [FromQuery]
    [OpenApiParameter(Description = "El ID de propiedad de integración. Se devolverán los eventos relacionados con las presentaciones relacionadas con este ID", Example = "123")]
    string propertyId)
{
    // ...
}

Esto también establecerá la descripción del parámetro y el valor de ejemplo, sin afectar al marcador de posición.

Answer

davy.ai

July 21, 2023 at 9:56 pm
Para cambiar el marcador de posición de un parámetro de consulta en Swashbuckle utilizando comentarios XML, puedes agregar un valor de ejemplo en tu comentario XML usando el siguiente formato:
```
/// <param name="nombreDelParametro" example="valorEjemplo">Descripción del parámetro
```
Por ejemplo, para cambiar el marcador de posición del parámetro “propertyId”, puedes modificar tu código de la siguiente manera:
```
/// <param name="propertyId" example="123">El ID de propiedad de integración. Se devolverán los eventos relacionados con las presentaciones relacionadas con este ID
public ActionResult GetEvents([BindRequired] string propertyId){}
```
Esto establecerá el marcador de posición del cuadro de texto del parámetro en “123”. Puedes reemplazar “123” con el valor de ejemplo que desees utilizar.

Alternativamente, puedes utilizar el atributo OpenApiParameter de Swashbuckle para personalizar la descripción del parámetro y el valor de ejemplo. Aquí tienes un ejemplo:
```
[HttpGet]
[OpenApiOperation("GetEvents", "Obtener eventos por ID de propiedad")]
public ActionResult<><event>> GetEvents(
    [BindRequired]
    [FromQuery]
    [OpenApiParameter(Description = "El ID de propiedad de integración. Se devolverán los eventos relacionados con las presentaciones relacionadas con este ID", Example = "123")]
    string propertyId)
{
    // ...
}
```
Esto también establecerá la descripción del parámetro y el valor de ejemplo, sin afectar al marcador de posición.

Comments are closed.

es.davy.ai

¿Tienes una pregunta?

Valores de ejemplo (espacios reservados) para los parámetros de consulta en Swagger (Swashbuckle).

Answer

davy.ai