Crear APIs que se integren a la perfección con estructuras de datos en evolución es crucial en el desarrollo de APIs. JSON Schema, un estándar ampliamente adoptado para la definición de APIs, proporciona un marco de trabajo robusto para definir estructuras de datos y reglas de validación en combinación con OpenAPI.
Dentro de este marco de trabajo, las palabras clave oneOf, anyOf y allOf emergen como herramientas poderosas para construir APIs flexibles y adaptables. oneOf ayuda a especificar múltiples esquemas válidos para una única estructura de datos.
anyOf proporciona un mecanismo para validar una estructura de datos contra otros esquemas disponibles. allOf combina múltiples opciones de esquema en una única regla de validación, asegurando que una estructura de datos se adhiere a todas las restricciones especificadas. Apidog ayuda a que las APIs se adapten a la perfección a diversas necesidades de datos.
Qué es oneOf
El término "oneOf" se refiere a una construcción o palabra clave utilizada en el contexto de definiciones de esquemas como los esquemas JSON. "oneOf" te permite especificar múltiples subesquemas, y una instancia válida del esquema debe adherirse a las restricciones de exactamente uno de estos subesquemas. Por ejemplo, considera un esquema JSON para una persona, donde una persona puede ser un adulto o un niño.
La palabra clave "oneOf" podría especificar dos subesquemas, uno para adultos y otro para niños. El documento que se está validando debe satisfacer las restricciones del esquema de adulto o de niño, pero no de ambos. Aquí está cómo se vería en un esquema JSON.
{
"type": "object",
"oneOf": [
{
"properties": {
"age": { "type": "integer", "minimum": 18 }
},
"required": ["age"]
},
{
"properties": {
"age": { "type": "integer", "maximum": 17 }
},
"required": ["age"]
}
]
}
En este ejemplo, la palabra clave "oneOf" se utiliza para definir dos subesquemas: uno para adultos y otro para niños. El documento que se está validando debe satisfacer las restricciones del esquema de adulto o de niño, pero no de ambos. La propiedad "age" es un discriminador para determinar qué subesquema debe aplicarse.
Esta flexibilidad es beneficiosa cuando tienes diversas estructuras válidas para un documento JSON basadas en diferentes condiciones. La palabra clave "oneOf" asegura la exclusividad mutua entre los subesquemas definidos, garantizando que una instancia válida se ajuste a solo una de las estructuras especificadas. Esta capacidad hace de "oneOf" una herramienta valiosa para describir con precisión modelos de datos complejos y mantener la integridad de los datos en varios escenarios.
Qué es anyOf
La palabra clave "anyOf" es otra construcción para definir un esquema donde la instancia validada debe ajustarse al menos a un subesquema especificado. A diferencia de "oneOf", que impone la adherencia exclusiva a un subesquema, "anyOf" ofrece más flexibilidad al permitir que la instancia satisfaga las restricciones de al menos uno de los subesquemas especificados.
Consideremos un escenario práctico donde "anyOf" podría ser beneficioso. Imagina trabajar con datos JSON que representan individuos, algunos adultos y otros estudiantes. Tanto los adultos como los estudiantes tienen propiedades distintas, y quieres crear un esquema que se adapte a ambos casos.
La palabra clave "anyOf" te permite expresar esta flexibilidad, permitiendo que el documento JSON sea válido si se ajusta al esquema para adultos o estudiantes. Aquí está cómo se representa este ejemplo en un esquema JSON.
{
"type": "object",
"anyOf": [
{
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 18 }
},
"required": ["name", "age"]
},
{
"properties": {
"name": { "type": "string" },
"grade": { "type": "string", "enum": ["A", "B", "C"] }
},
"required": ["name", "grade"]
}
]
}
En este ejemplo, la palabra clave "anyOf" se utiliza para definir dos subesquemas: uno para adultos y otro para estudiantes. El documento JSON se considera válido si satisface las restricciones del esquema de adulto o de estudiante. Esto permite una representación flexible de diversas estructuras de datos dentro del mismo esquema general, haciendo de "anyOf" una herramienta poderosa para manejar variados escenarios de datos.
OneOf vs anyof: ¿Cuál es la diferencia en el esquema z?
En Z Schema, OneOf y AnyOf se utilizan para definir múltiples esquemas, pero tienen diferentes propósitos.
OneOf:
OneOf se utiliza cuando exactamente uno de los esquemas definidos debe coincidir.
Asegura que los datos se validen contra solo uno de los esquemas especificados.
Ejemplo:
{
"OneOf": [
{"type": "string"},
{"type": "number"}
]
}
Este esquema asegura que los datos sean una cadena o un número, pero no ambos.
AnyOf:
AnyOf se utiliza cuando cualquiera o más de los esquemas definidos pueden coincidir.
Permite que los datos se validen contra múltiples esquemas especificados.
Ejemplo:
{
"AnyOf": [
{"type": "string"},
{"type": "number"}
]
}
Qué es allOf
La palabra clave "allOf" en JSON Schema define un esquema donde la instancia validada debe ajustarse a todos los subesquemas especificados. Esencialmente, representa una operación lógica AND para los subesquemas. Esto significa que el documento JSON validado debe satisfacer las restricciones de cada subesquema listado bajo "allOf". Aquí hay un ejemplo:
{
"allOf": [
{
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 18 }
},
"required": ["name", "age"]
},
{
"properties": {
"hasDegree": { "type": "boolean", "default": true }
},
"required": ["hasDegree"]
}
]
}
En este ejemplo, la palabra clave "allOf" combina dos subesquemas. El primer subesquema define propiedades para adultos, incluyendo un nombre y edad con restricciones específicas. El segundo subesquema introduce una propiedad para individuos con un título, en este caso, una propiedad booleana "hasDegree" con un valor predeterminado de true. El efecto combinado de "allOf" es que el documento JSON validado debe adherirse a ambas restricciones. Debe tener un nombre, edad (satisfaciendo el primer subesquema), y también incluir la propiedad "hasDegree" (satisfaciendo el segundo subesquema).
La palabra clave "allOf" es útil cuando se crea un esquema que abarca las propiedades y restricciones de múltiples subesquemas, asegurando que la instancia validada cumpla con todas las condiciones especificadas. Esta operación lógica AND difiere de "anyOf" y "oneOf", permitiendo flexibilidad al satisfacer al menos uno o exactamente uno de los subesquemas especificados.
¿Qué es Apidog?
Apidog es una plataforma de integración de APIs versátil que simplifica las pruebas, la depuración, el diseño, la simulación y la documentación de APIs. Ofrece una interfaz fácil de usar, herramientas de colaboración y características para evaluaciones exhaustivas de APIs.
Apidog destaca en la documentación de respuestas de API con diseños personalizables y facilita los esfuerzos de colaboración dentro de los equipos. Sus herramientas de prueba permiten la adición visual de aserciones y la creación de ramas de prueba. La plataforma también ayuda a monitorear la actividad de la API y proporciona capacidades de simulación eficientes, eliminando la necesidad de scripting en el desarrollo.
Esquemas JSON de Apidog con oneOf, anyOf y allOf
Ahora que sabes qué son los esquemas JSON y cómo emplean oneOf, anyOf y allOf en su estructura, los definiremos en Apidog. Para crear eficientemente estos esquemas en Apidog, asegúrate de tener Apidog descargado en tu sistema o tener una cuenta para usar los servicios de Apidog en línea.
Cómo crear OneOf
- Crea un nuevo proyecto en Apidog con tipo HTTP.
2. Crea un nuevo Esquema haciendo clic en el botón de nuevo Esquema.
3. Haz clic en la opción Generar desde JSON y ve a la opción de esquema JSON.
4. Introduce el siguiente código en el editor.
{
"title": "Payment Schema Example",
"type": "object",
"properties": {
"payment": {
"oneOf": [
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"required": ["amount", "currency"]
},
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
},
"cardDetails": {
"type": "object",
"properties": {
"cardNumber": {
"type": "string"
},
"expirationDate": {
"type": "string"
},
"cvv": {
"type": "string"
}
},
"required": ["cardNumber", "expirationDate", "cvv"]
}
},
"required": ["amount", "currency", "cardDetails"]
}
]
}
},
"required": ["payment"]
}
5. Guarda tu esquema.
¡Tu esquema oneOf ha sido creado con éxito!
Cómo crear anyOf
Sigue todos los pasos anteriores para oneOf, pero el único cambio que harás para tu esquema anyOf es cambiar el código. Introduce el siguiente código en el editor para crear tu esquema.
{
"type": "object",
"properties": {
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"zip": {
"type": "string"
}
},
"required": ["street", "city", "state", "zip"]
},
{
"type": "object",
"properties": {
"country": {
"type": "string"
}
},
"required": ["country"]
}
]
}
},
"required": ["address"]
}
allOf
Sigue todos los pasos anteriores para oneOf, pero el único cambio que harás para tu esquema allOf es cambiar el código. Introduce el siguiente código en el editor para crear tu esquema.
{
"type": "object",
"properties": {
"product": {
"allOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": ["name", "description"]
},
{
"type": "object",
"properties": {
"price": {
"type": "number"
},
"stock": {
"type": "integer"
}
},
"required": ["price", "stock"]
}
]
}
},
"required": ["product"]
}
Beneficios de crear esquemas con Apidog
Puedes hacer varias cosas útiles ahora que has creado tus esquemas JSON con Apidog. Algunos de los beneficios se mencionan a continuación.
Documentación de la API
Puedes integrar tu esquema JSON en tu documentación de API para proporcionar descripciones claras y completas de las estructuras de datos y las reglas de validación de los puntos finales de tu API. Esto mejora la comprensión del desarrollador y reduce el riesgo de errores en el uso de la API.
Generación de código
Puedes utilizar herramientas como las capacidades de generación de código de Apidog para generar automáticamente bibliotecas de cliente y código del lado del servidor a partir de tu esquema JSON. Esto agiliza el proceso de desarrollo y garantiza la coherencia entre la definición de tu API y su implementación.
Validación de datos y manejo de errores
Puedes emplear bibliotecas de validación de esquemas JSON para validar las solicitudes y respuestas de API entrantes, asegurando que los datos se ajusten a la estructura y las restricciones definidas. Esto ayuda a evitar que datos no válidos entren en tu sistema y reduce el riesgo de errores de aplicación.
Pruebas de API
Puedes aprovechar el esquema JSON para generar casos de prueba para los puntos finales de tu API y crear servidores simulados para las pruebas. Esto facilita las pruebas de API integrales y garantiza que tu API funcione según lo previsto.
Diseño de API
Puedes refinar continuamente tu esquema JSON a medida que tu API evoluciona para adaptarse a los nuevos requisitos de datos y patrones de uso. Esto garantiza que tu API siga siendo flexible y adaptable a las demandas cambiantes.
Conclusión
En conclusión, la integración de esquemas JSON con Apidog puede mejorar enormemente el proceso de documentación de las APIs. JSON Schema proporciona una forma estandarizada de describir la estructura y las restricciones de los datos JSON, y cuando se integra con las herramientas de documentación de la API, garantiza que la documentación refleje con precisión los formatos de solicitud y respuesta esperados.
Apidog admite funciones que aprovechan los esquemas JSON. Por ejemplo, podría generar automáticamente documentación basada en los esquemas definidos, lo que facilita mantener la documentación actualizada a medida que la API evoluciona.
