Configurar múltiples ejemplos de cuerpo de petición

Apidog admite la configuración de múltiples ejemplos para cuerpos de petición de tipo JSON, XML, Raw y MsgPack. Esta función resulta útil para:

Configurar ejemplos para diferentes escenarios de negocio: Por ejemplo, peticiones normales frente a peticiones de excepción.

Cumplimiento de las especificaciones OAS 3.0/3.1: Admite la exportación de especificaciones OpenAPI estándar.

Cambiar rápidamente entre ejemplos: Útil durante la depuración y las pruebas automatizadas.

Configurar múltiples ejemplos de cuerpo de petición

Se requiere Apidog versión 2.7.0 o posterior.

Crear un nuevo ejemplo de cuerpo de petición

Vaya a la página Edit de la documentación de su endpoint.

Localice la sección Request Body.

Haga clic en el botón + Add para crear un nuevo ejemplo de cuerpo de petición.

Configurar el ejemplo de cuerpo de petición

Nombre del ejemplo (opcional): Si se deja en blanco, se usará de forma predeterminada Example 1, Example 2, etc.

Valor del ejemplo (obligatorio): Proporcione los datos de ejemplo reales para el cuerpo de la petición.

Descripción (opcional): Añada una descripción para explicar el ejemplo. Admite formato Markdown para texto enriquecido.

Clave OAS (opcional): Se utiliza al exportar especificaciones OpenAPI. Si no se proporciona, se usará un número de serie en su lugar.

Extensiones OAS (campos personalizados): Si se proporcionan, se conservarán durante la exportación.

Configurar ejemplo de cuerpo de petición

Guardar y usar el ejemplo de cuerpo de petición

Una vez que haya guardado el ejemplo, estará disponible para su uso. Durante la depuración, puede seleccionar fácilmente diferentes ejemplos para probar sus endpoints.

Usar ejemplo de cuerpo de petición durante la depuración

TIP

Para cuerpos de petición de tipo Raw, solo se muestra el primer valor de ejemplo durante la depuración.

Extraer parámetros de petición como ejemplos

Durante la depuración, si ha configurado manualmente el cuerpo de la petición y desea guardarlo como ejemplo, simplemente haga clic en: Extract > Extract to "Request Example".

Elegir la opción de extracción

Se le solicitará que elija cómo guardar los parámetros de petición:

Sobrescribir el ejemplo: Reemplaza un ejemplo guardado previamente.

Nuevo ejemplo: Lo guarda como un ejemplo completamente nuevo.

TIP

El valor de depuración actual se rellenará automáticamente en el ejemplo de forma predeterminada.

Escenarios de uso

Usar ejemplos de cuerpo de petición durante la depuración

Vaya a la página Run de la documentación del endpoint y localice la sección Auto-generate.

Haga clic en el menú desplegable para seleccionar un ejemplo de cuerpo de petición. El ejemplo se completará automáticamente.

Cambiar ejemplos de cuerpo de petición durante la depuración

Puede cambiar entre ejemplos en tiempo real y enviar peticiones con el ejemplo seleccionado.

Configuración avanzada

Haga clic en el icono desplegable junto a Auto-generate para acceder a las siguientes opciones:

EXAMPLES: Elija entre ejemplos de cuerpo de petición predefinidos.

Generate Each Time: Genera automáticamente valores aleatorios basados en reglas de mock.

Auto-generation Preference: Para configuraciones más avanzadas, consulte Generate Requests.

Visualización de la documentación

Para un único ejemplo de cuerpo de petición: Se muestra en una vista simplificada sin mostrar el nombre del ejemplo.

Visualización de un único cuerpo de petición

Para múltiples ejemplos de cuerpo de petición: Permite cambiar entre ejemplos en un diseño lado a lado, mostrando nombres de ejemplo y descripciones en Markdown.

Visualización de ejemplos de cuerpo de petición

Orden de visualización

El orden de visualización de los ejemplos de cuerpo de petición sigue esta prioridad:

Nombre del ejemplo > Clave OAS > Número de serie (incrementado automáticamente desde 1).

Los elementos no vacíos se muestran primero.

Cumplimiento con OAS

Clave OAS

La clave OAS controla los nombres de campo de los ejemplos al exportar especificaciones OpenAPI.

Configuración: Rellene la Clave OAS para los ejemplos de cuerpo de petición.

Configurar clave OAS del cuerpo de petición

Reglas de exportación:

Cuando se rellena: La clave OAS proporcionada se utiliza como nombre de campo dentro del objeto examples.

Cuando no se rellena: Los números de serie (empezando desde 1) se utilizan automáticamente como nombres de campo.

Cuando se rellena

Cuando no se rellena:

 "examples": {
   "example1": {
      "value": {
        "name": "Blake Keeling",
        "id": "165061",
        "email": "Blake.Keeling@gmail.com"
      },
      "summary": "example1",
      "description": "This is`example 1`"
    },
    "example2": {
       "value": {
        "name": "Jolie Kutch",
        "id": "138164",
        "email": "Jolie_Kutch@hotmail.com"
      },
      "summary": "example 2",
      "description": "This is`example 2`"
    }
  }

"examples": {
   "1": {
     "value": {
       "name": "Blake Keeling",
       "id": "165061",
       "email": "Blake.Keeling@gmail.com"
     },
     "summary": "example1",
     "description": "This is`example 1`"
   },
    "2": {
      "value": {
       "name": "Jolie Kutch",
       "id": "138164",
       "email": "Jolie_Kutch@hotmail.com"
     },
     "summary": "example 2",
     "description": "This is`example 2`"
   }
 }

Extensiones OAS

Puede añadir extensiones personalizadas de OpenAPI Specification (OAS) a los ejemplos.

Configuración: Introduzca pares clave-valor JSON en el campo Extensión OAS.

{
  "x-demo": true,
  "x-scenario": "error_case"
}

Efecto de exportación: Las extensiones OAS personalizadas se conservarán por completo y se incluirán en las especificaciones OpenAPI exportadas.

"examples": {
    "example1": {
      "x-demo": true,
      "x-scenario": "error_case",
      "value": {
         "name": "Blake Keeling",
         "id": "165061",
         "email": "Blake.Keeling@gmail.com"
      },
      "summary": "example1",
      "description": "This is`example 1`"
    }
}

Preguntas frecuentes

¿Cómo habilitar múltiples ejemplos de cuerpo de petición en proyectos antiguos?

No se requiere ninguna acción manual. Cuando añade un segundo ejemplo de cuerpo de petición a un endpoint existente, el sistema actualiza automáticamente el formato para admitir múltiples ejemplos.

¿Cómo gestionar múltiples ejemplos de cuerpo de petición al exportar OAS?

¿Cambiará el orden de los ejemplos de cuerpo de petición en el OAS exportado?

¿Cómo hacer que los nombres de ejemplo exportados sean más intuitivos?

Configurar múltiples ejemplos de cuerpo de petición

Configurar múltiples ejemplos de cuerpo de petición#

Extraer parámetros de petición como ejemplos#

Escenarios de uso#

Usar ejemplos de cuerpo de petición durante la depuración#

Visualización de la documentación#

Cumplimiento con OAS#

Clave OAS#

Extensiones OAS#

Preguntas frecuentes#

Configurar múltiples ejemplos de cuerpo de petición

Extraer parámetros de petición como ejemplos

Escenarios de uso

Usar ejemplos de cuerpo de petición durante la depuración

Visualización de la documentación

Cumplimiento con OAS

Clave OAS

Extensiones OAS

Preguntas frecuentes