Crear un esquema

Uso del Editor de esquemas

El Editor de esquemas es una herramienta eficaz que ayuda a diseñar y modelar las estructuras de datos que utiliza su API. Se basa en JSON Schema y se utiliza para diseñar estructuras de datos JSON o XML.

Utilice el Editor de esquemas para:

Desarrollar cuerpos de peticiones y respuestas de API adaptados a endpoints de API específicos.

Construir modelos de datos que sean aplicables en una o varias API.

Cada esquema comienza con un objeto raíz. Para crear un esquema, agregue propiedades a este objeto raíz.

Agregar propiedades

Haga clic en el signo + (Agregar un nodo secundario) junto al objeto raíz para introducir nuevas propiedades.

Nombrar su propiedad

Introduzca el nombre (o clave) de la propiedad.

Seleccionar el tipo de propiedad

Elija tipos de datos comunes o seleccione referencias a esquemas predefinidos.

Configuración avanzada

Utilice el Editor de tipos para asignar tipos de datos, como valores predeterminados y formatos, a cada propiedad.

Administrar propiedades

Reordene las propiedades moviéndolas, copiándolas o eliminándolas. También puede enriquecer las propiedades con descripciones y marcarlas como obligatorias.

Métodos alternativos

También puede crear nuevos esquemas importándolos desde tablas de base de datos o archivos de esquema JSON. Obtenga más información sobre Generar esquemas a partir de JSON, etc..

Tipo de propiedad

De acuerdo con el estándar JSON Schema, el Editor de esquemas de Apidog admite los siguientes tipos de datos básicos:

Tipo	Descripción
null	Representa un valor JSON "null".
boolean	Representa un valor "true" o "false", correspondiente al valor JSON "true" o "false".
object	Representa una colección no ordenada de pares clave-valor, correspondiente al valor JSON "object".
array	Representa una lista ordenada de valores, correspondiente al valor JSON "array".
number	Representa un valor numérico decimal de base 10 y precisión arbitraria, correspondiente al valor JSON "number".
string	Representa una cadena de caracteres Unicode, correspondiente al valor JSON "string".

Tipo de datos Array

Al usar el tipo de datos array, se generará automáticamente una propiedad de subnivel ITEMS. Esta especifica el tipo de datos de los elementos dentro del array.

Además de las estructuras de datos estándar mencionadas anteriormente, el Editor de esquemas de Apidog también admite lo siguiente:

Referenciar otros esquemas: capacidad para referenciar y reutilizar esquemas definidos en otra parte de la documentación de la API.

any: representa un valor que puede ser de cualquier tipo de datos.

Composición de esquemas: permite combinar varios esquemas para crear estructuras de datos complejas.

Personalización: permite a los usuarios personalizar y adaptar el esquema para cumplir requisitos específicos y necesidades de modelado de datos.

Referenciar otros esquemas

Puede utilizar la función "Referenciar otros esquemas" para referenciar esquemas definidos previamente.

Después de referenciar otro esquema, puede ver el esquema referenciado en el Editor de esquemas.

Puntos clave sobre los esquemas referenciados:

Cualquier modificación realizada en el esquema original se reflejará en el esquema que lo referencia.

El esquema referenciado no se puede editar directamente; para realizar cambios, puede:

Hacer clic en el nombre del esquema para navegar al esquema original y editarlo.

Al hacer clic en Anular referencia en el esquema, el esquema se transformará en una serie de propiedades independientes, lo que le permitirá editarlas individualmente.

Si necesita modificar de forma independiente la definición de una propiedad específica, puede elegir Anular referencia para esa propiedad, lo que permite modificaciones individuales. Cualquier cambio en el esquema original no afectará a la propiedad cuya referencia se haya anulado.

En los casos en que no se requieran todas las propiedades del esquema referenciado en el endpoint, puede hacer clic en Ocultar para ocultar las propiedades innecesarias.

Composición de esquemas

Si una propiedad de su estructura de datos puede tener varios tipos de datos posibles, puede usar la Composición de esquemas para combinar varios esquemas.

Apidog admite las siguientes palabras clave de composición:

Palabra clave	Descripción
allOf (AND)	Especifica que la propiedad debe ajustarse a todos los esquemas definidos en la composición.
anyOf (OR)	Especifica que la propiedad puede ajustarse a cualquiera de los esquemas enumerados en la composición.
oneOf (XOR)	Especifica que la propiedad debe ajustarse a uno y solo uno de los esquemas definidos en la composición.

Después de seleccionar Composición de esquemas, aparecerán subpropiedades llamadas "0" y "1" debajo de la propiedad, que representan cada esquema dentro de la composición. Puede modificar el tipo de esquema de cada subpropiedad y agregar esquemas adicionales según sea necesario.

En la documentación de la API, la Composición de esquemas se mostrará así:

Observará los dos objetos opcionales debajo de OneOf. Si desea mostrar sus nombres como se muestra en la imagen, debe introducir los nombres en el campo title del Editor de tipos.

Personalización

Al elegir "Personalizar", puede editar directamente el JSON Schema dentro del editor.

Configuración de propiedades

Para cada propiedad, hay varios botones ubicados junto al tipo de datos:

Botón	Descripción
*	Indica si la propiedad es obligatoria.
N	Especifica si la propiedad permite valores nulos.
Settings	Le permite editar la configuración avanzada en el Editor de tipos.

Editor de tipos

El Editor de tipos describe visualmente una propiedad de acuerdo con JSON Schema.

Una vez configurados estos ajustes avanzados, surtirán efecto en las siguientes áreas:

Al agregar ejemplos de respuesta, puede hacer clic para generarlos automáticamente en función de la configuración.

Se mostrarán en la documentación de la API.

En el cuerpo de la petición, puede hacer clic para generarlo automáticamente en función de la configuración.

Al enviar una petición, los datos devueltos se validarán automáticamente con la configuración.

En el servicio mock, los datos de respuesta se generarán en función de la configuración.

Propiedad enumerada

Para los tipos String, Integer y Number, Apidog admite enum. Al activar el interruptor de enum, puede agregar valores y descripciones de enum. Además, puede realizar una edición masiva de los valores de enum.

Mock

Además de la configuración avanzada de la propiedad, puede especificar contenido mock para los campos rellenando valores mock. Los valores mock tienen prioridad sobre la configuración avanzada.

Los valores mock admiten la sintaxis de Faker.js, lo que le permite elegir los datos faker deseados directamente desde las opciones desplegables.

Los valores mock también se pueden introducir como valores fijos.

Configuración XML

Para datos XML, el Editor de tipos en Apidog ofrece configuración XML adicional. Puede habilitar el interruptor XML, configurar propiedades como el nombre de la etiqueta, el espacio de nombres, etc., y previsualizar la estructura XML correspondiente.

HashMap, diccionario, array

HashMap, también conocido como Map, diccionario o array asociativo. Es una colección de pares clave-valor, donde los nombres de las claves pueden ser cualquier contenido, en lugar de estar predefinidos.

La especificación OpenAPI admite la definición de un HashMap con claves de cadena. Esto se hace estableciendo el tipo de elemento en object y luego usando la palabra clave additionalProperties para especificar el tipo de los valores en los pares clave-valor.

Suponga que hay una API de consulta de información de usuarios y que el formato de los datos devueltos tiene los siguientes requisitos:

Los datos devueltos son un objeto

Los elementos secundarios del objeto son pares clave-valor de un HashMap

El ID de usuario es la clave y la información del usuario es el valor

Para definir esto en Apidog:

Cree un nuevo esquema y asígnele el nombre "UserProfiles".

En "UserProfiles", especifique el nodo raíz como tipo "object". Luego haga clic en Configuración avanzada, establezca additionalProperties en Permitir y haga clic en el botón Configuración de la derecha.

En la ventana emergente, agregue la información de usuario requerida, con el nombre y el correo electrónico del usuario como campos del objeto. Se guarda automáticamente.

Agregar campos de información de usuario

En las respuestas de la documentación de la API, referencie el esquema en el nodo raíz y seleccione "user profiles", que acaba de crear.

Referenciar el esquema de perfiles de usuario

Haga clic en guardar y, a continuación, podrá ver el esquema definido y los valores de ejemplo en el ejemplo de respuesta devuelta dentro de la documentación de la API.

Ejemplo de esquema en la documentación de la API

Objetos con additionalProperties

A medida que el trabajo de desarrollo real evoluciona, los objetos devueltos por la API pueden tener additionalProperties en comparación con el objeto definido originalmente. Según la especificación OpenAPI, esta situación también se puede gestionar mediante la función "additionalProperties".

Suponga que ahora existe una API de consulta de información de usuarios, en la que los campos de respuesta definidos originalmente al consultar información de usuario por ID de usuario eran name y email. Ahora, con la actualización del sistema, desea incluir otros campos.

Al editar la documentación de la API, puede definirlo de la siguiente manera: en el nodo raíz del modelo de datos, haga clic en Configuración avanzada, establezca additionalProperties en Permitir y establezca el tipo de valor del campo en any.

Luego puede ver la estructura de datos definida y los valores de ejemplo en la documentación de la API.

Estructura de datos con additionalProperties

Tuplas

Por lo general, los elementos internos de un array deben ser del mismo tipo, mientras que las tuplas pueden contener diferentes tipos de datos. Si desea definir una tupla que incluya tipos string e integer, como datos del tipo (0,"A",2,"C"), puede establecer el tipo de elemento en array en el modelo de datos, luego establecer el tipo de items en anyOf en el patrón de combinación y, a continuación, agregar elementos secundarios de tipo string e integer, respectivamente.

TIP

Si desea generar varios elementos al generar ejemplos, especifique el número mínimo y máximo de elementos en la configuración avanzada del nodo raíz.

Después de guardar, haga clic en Generar automáticamente en la documentación de la API para ver la estructura de datos definida y los valores de ejemplo.

También puede ver los valores de ejemplo de la tupla en la respuesta devuelta en la documentación.

Herramientas

El Editor de esquemas en Apidog proporciona varias herramientas muy útiles.

Herramienta	Descripción
Generate from JSON etc.	Esta herramienta le permite generar esquemas automáticamente a partir de JSON, datos XML y otras fuentes, o directamente desde estructuras de tablas de base de datos. Obtenga más información sobre Generar esquemas a partir de JSON, etc..
Preview	Esta herramienta crea datos mock que se ajustan a la definición del esquema, proporcionando una vista previa de los datos esperados.
Generate code	Esta herramienta puede producir código de definición de estructuras de datos en varios lenguajes de programación. Obtenga más información sobre Generar código.
JSON Schema	Esta herramienta permite la edición directa de esquemas JSON para ajustes precisos y personalización.

Preguntas frecuentes

P: Si una propiedad de cadena tiene varios valores enumerados y se usa en varias ubicaciones, ¿cómo se puede referenciar este enum de forma coherente en todas ellas?

R: Puede definir esta propiedad como un esquema independiente que conste de una sola propiedad, lo que permite referenciarla de forma coherente en diferentes partes de la documentación de la API.

Crear un esquema

Uso del Editor de esquemas#

Crear un esquema#

Tipo de propiedad#

Referenciar otros esquemas#

Composición de esquemas#

Personalización#

Configuración de propiedades#

Editor de tipos#

Propiedad enumerada#

Mock#

Configuración XML#

HashMap, diccionario, array#

Objetos con additionalProperties#

Tuplas#

Herramientas#

Preguntas frecuentes#

Uso del Editor de esquemas

Crear un esquema

Tipo de propiedad

Referenciar otros esquemas

Composición de esquemas

Personalización

Configuración de propiedades

Editor de tipos

Propiedad enumerada

Mock

Configuración XML

HashMap, diccionario, array

Objetos con additionalProperties

Tuplas

Herramientas

Preguntas frecuentes