Apidog admite añadir múltiples ejemplos de cuerpo de solicitud para cada endpoint, lo que hace que la documentación de tu API sea más útil y compatible con las especificaciones de OpenAPI. Esta función te permite mostrar diferentes formas de estructurar las solicitudes para el mismo endpoint, lo que ayuda a los desarrolladores a comprender cómo usar tu API en diversas situaciones.
Los ejemplos de cuerpo de solicitud son útiles porque:
- Muestran a los desarrolladores exactamente cómo formatear sus solicitudes
- Demuestran diferentes casos de uso para el mismo endpoint
- Facilitan las pruebas al proporcionar estructuras de solicitud listas para usar
- Aseguran que tu documentación siga los estándares de OpenAPI
Puedes añadir tantos como necesites para cubrir todos los escenarios posibles.
Paso a paso: Añadir tu primer ejemplo de cuerpo de solicitud
Añadir ejemplos de cuerpo de solicitud en Apidog es sencillo. Aquí te mostramos cómo empezar:
1. Abre tu proyecto de API en Apidog (versión 2.7.0 o superior)
2. Navega al endpoint donde quieres añadir ejemplos
3. Haz clic en la pestaña "Edit" para acceder al editor de documentación y desplázate a la sección "Request Body"
4. Haz clic en "Add Exampe" para crear un nuevo ejemplo
5. Rellena los detalles del ejemplo:
- Example Name: Dale a tu ejemplo un nombre claro (p. ej., "Solicitud estándar")
- Example Value: Introduce los datos reales en formato JSON, XML u otro formato
- Description: Explica cuándo usar este ejemplo (admite Markdown)
- OAS Key: Proporciona un identificador para la exportación de OpenAPI (opcional, pero recomendado)
- OAS Extensions: Añade cualquier campo personalizado necesario para la exportación (opcional)
6. Haz clic en "Save" para crear el ejemplo
El nombre del ejemplo ayuda a los usuarios a identificar el propósito de cada ejemplo. Si lo dejas en blanco, Apidog lo nombrará automáticamente "Ejemplo 1", "Ejemplo 2", etc.
El valor del ejemplo debe mostrar una estructura de solicitud válida. Para los tipos de contenido JSON, Apidog proporciona un editor estructurado para ayudar a garantizar un formato válido.
El campo de descripción es donde puedes explicar cuándo y por qué alguien usaría esta estructura de solicitud en particular. Usar Markdown aquí puede hacer que tus explicaciones sean más claras.
La OAS Key es importante si planeas exportar tu documentación al formato OpenAPI. Esta clave se convierte en el identificador del ejemplo en la especificación exportada.
Crear múltiples ejemplos para diferentes escenarios
Después de añadir tu primer ejemplo, querrás crear ejemplos adicionales para diferentes casos de uso:
- Haz clic en el botón "+ Add" de nuevo para crear otro ejemplo
- Dale un nombre distinto que identifique claramente el escenario (p. ej., "Solicitud mínima")
- Introduce el valor del ejemplo para este escenario específico
- Añade una descripción detallada que explique cuándo usar este ejemplo
- Configura la OAS Key y las Extensions según sea necesario
- Haz clic en "Save" para añadir el ejemplo
- Repite este proceso para todos los escenarios relevantes
Al crear múltiples ejemplos, considera cubrir estos escenarios comunes:
- Standard Request: La forma típica de usar el endpoint
- Minimal Request: La estructura de solicitud válida más simple
- Complete Request: Una solicitud que utiliza todos los campos posibles
- Special Case: Ejemplos para escenarios comerciales únicos
Cada ejemplo debe mostrar una forma diferente de usar el endpoint. Esto ayuda a los desarrolladores a comprender la gama completa de posibilidades al trabajar con tu API.
Apidog muestra los ejemplos en un orden específico:
- Los ejemplos con nombres aparecen antes que los ejemplos sin nombre
- Los ejemplos con OAS Keys se muestran antes que los que no tienen
- Los ejemplos sin nombres ni OAS Keys se ordenan por sus números de serie
Para que tus ejemplos más importantes aparezcan primero, dales nombres claros y OAS Keys.
Usar ejemplos de cuerpo de solicitud para pruebas
Una de las mejores características de los múltiples ejemplos de cuerpo de solicitud es cómo simplifican las pruebas:
- Navega a la página "Run" de tu endpoint
- Encuentra la sección "Auto-generate" en la configuración de la solicitud
- Haz clic en el menú desplegable para ver todos los ejemplos disponibles
- Selecciona el ejemplo que quieres probar
- El cuerpo de la solicitud se rellenará automáticamente con el ejemplo seleccionado
- Haz clic en "Send" para probar el endpoint con este ejemplo
Esto facilita la prueba de diferentes escenarios sin tener que escribir o pegar manualmente diferentes estructuras de solicitud. Puedes cambiar rápidamente entre ejemplos para ver cómo tu API maneja varias entradas.
Apidog también te permite crear ejemplos a partir de tus sesiones de prueba:
- Configura un cuerpo de solicitud en la página "Run"
- Haz clic en el botón "Extract"
- Selecciona "Extract to Request Example"
- Elige crear un nuevo ejemplo o actualizar uno existente
- Tu cuerpo de solicitud actual se guardará como un ejemplo
Esto es útil cuando has encontrado una estructura de solicitud que funciona durante las pruebas y quieres guardarla para referencia o documentación futura.
Asegurar la compatibilidad con OpenAPI con tus ejemplos
Los ejemplos de cuerpo de solicitud de Apidog están diseñados para funcionar sin problemas con las especificaciones de OpenAPI. Cuando exportas la documentación de tu API, todos tus ejemplos se formatean correctamente según los estándares OAS 3.0/3.1.
Así es como se manejan los ejemplos durante la exportación:
- Cada ejemplo se incluye en la especificación exportada
- Los nombres de los ejemplos provienen de la OAS Key si se proporciona (o números de serie si no)
- Las descripciones de los ejemplos se conservan en el formato exportado
- Cualquier OAS Extension personalizada se incluye en la exportación
La especificación OpenAPI exportada incluirá tus ejemplos en una estructura como esta:
"examples": {
"standard_request": {
"value": {
"name": "John Doe",
"id": "12345",
"email": "john.doe@example.com"
},
"summary": "Standard Request",
"description": "This is a standard request with all required fields."
},
"minimal_request": {
"value": {
"id": "12345"
},
"summary": "Minimal Request",
"description": "This is a minimal request with only the required ID field."
}
}
Para garantizar la mejor compatibilidad con OpenAPI:
- Usa OAS Keys significativas para todos los ejemplos
- Proporciona descripciones claras que expliquen el propósito de cada ejemplo
- Revisa tus especificaciones exportadas para verificar que todo se vea correcto
Esto asegura que tus ejemplos sigan siendo valiosos no solo dentro de Apidog, sino también cuando se comparten a través de las especificaciones de OpenAPI.
Mejores prácticas para ejemplos de cuerpo de solicitud
Para obtener el máximo valor de los múltiples ejemplos de cuerpo de solicitud, sigue estas mejores prácticas:
Crear conjuntos de ejemplos completos
Incluye ejemplos que cubran:
- Uso básico con solo los campos requeridos
- Uso típico con campos opcionales de uso común
- Uso completo que muestre todos los campos posibles
- Casos límite que demuestren situaciones especiales
Usar nombres claros
- Dale a cada ejemplo un nombre descriptivo que indique su propósito
- Usa patrones de nomenclatura consistentes en diferentes endpoints
- Evita nombres genéricos como "Ejemplo 1" que no expliquen el contenido
Escribir descripciones útiles
- Explica cuándo y por qué alguien usaría cada ejemplo
- Menciona cualquier consideración especial para esta estructura de solicitud
- Usa el formato Markdown para que las descripciones sean más fáciles de leer
- Incluye las respuestas esperadas cuando sea relevante
Organizar los ejemplos lógicamente
- Pon los escenarios más comunes primero
- Agrupa los ejemplos relacionados
- Elimina los ejemplos obsoletos para evitar confusiones
- Actualiza los ejemplos cuando tu API cambie
Usar las OAS Keys de manera efectiva
- Elige claves significativas que describan el propósito del ejemplo
- Usa nombres de clave consistentes en toda tu API
- Evita los caracteres especiales que puedan causar problemas en las exportaciones
Siguiendo estas prácticas, crearás ejemplos de cuerpo de solicitud que realmente ayudarán a los desarrolladores a comprender y usar tu API de manera efectiva.
Conclusión
Añadir múltiples ejemplos de cuerpo de solicitud en Apidog es una forma simple pero poderosa de mejorar la documentación de tu API. Al mostrar diferentes formas de estructurar las solicitudes para el mismo endpoint, ayudas a los desarrolladores a comprender cómo usar tu API en diversas situaciones.
El proceso paso a paso es sencillo:
- Navega a tu endpoint y haz clic en "Edit"
- Desplázate a la sección Request Body y haz clic en "+ Add"
- Configura tu ejemplo con un nombre, valor, descripción y OAS Key
- Repite para escenarios adicionales
- Usa tus ejemplos para pruebas y documentación
Con los ejemplos adecuados, tu API se vuelve más fácil de entender, probar e implementar. Esto conduce a una adopción más rápida, menos preguntas de soporte y una mejor experiencia general para el desarrollador.
Empieza a añadir múltiples ejemplos de cuerpo de solicitud a tu documentación de Apidog hoy mismo para ver los beneficios por ti mismo y para los usuarios de tu API.
