I/O Docs es un sistema interactivo para la documentación de APIs que facilita la creación, gestión y prueba de endpoints. A continuación, se detalla cómo manejar configuraciones avanzadas para arreglos, objetos y el cuerpo de la petición, mejorando la claridad y usabilidad de tus especificaciones.

Configuración de Arreglos

Los arreglos son comunes en el desarrollo de APIs. I/O Docs permite configurarlos de diversas formas para adaptarse a distintos requerimientos.

Definición de Arreglos Simples

Para definir un arreglo básico, se especifica el tipo array y el tipo de sus elementos mediante items.

"listaBasica": {
  "type": "array",
  "items": {
    "title": "listaBasica",
    "default": "",
    "type": "string",
    "description": "Lista de cadenas en el cuerpo",
    "required": true
  }
}

Arreglos Reutilizables

Para evitar la duplicación de código, puedes definir modelos de arreglos y referenciarlos usando $ref.

"arregloReutilizable": {
  "type": "array",
  "items": {
    "title": "arregloCabecera",
    "default": "valor",
    "type": "string",
    "description": "Arreglo referenciado ubicado en la cabecera.",
    "location": "header",
    "required": true
  }
}

Al utilizarlo en otra parte de la configuración:

"arregloReferenciado": {
  "$ref": "arregloReutilizable"
}

Arreglos de Valores Restringidos (Enum)

Cuando los elementos del arreglo deben limitarse a un conjunto específico de opciones, se emplea la propiedad enum.

"listaOpciones": {
  "type": "array",
  "location": "header",
  "items": {
    "title": "opcionesPermitidas",
    "required": false,
    "type": "string",
    "enum": ["opcionA", "opcionB"],
    "description": "Arreglo con valores restringidos."
  }
}

Configuración de Objetos

Los objetos permiten estructurar datos complejos. I/O Docs soporta objetos planos, anidados y reutilizables.

Objetos Básicos

Un objeto simple se define con type: "object" y una sección de properties.

"objetoSencillo": {
  "type": "object",
  "location": "body",
  "properties": {
    "campoUno": {
      "title": "campoUno",
      "required": false,
      "type": "string",
      "description": "Primer elemento del cuerpo.",
      "default": "valor1"
    },
    "campoDos": {
      "title": "campoDos",
      "required": false,
      "type": "string",
      "description": "Segundo elemento del cuerpo.",
      "default": "valor2"
    }
  }
}

Objetos Anidados

Se pueden crear estructuras jerárquicas profundas definiendo objetos dentro de las propiedades de otros objetos.

"objetoAnidado": {
  "type": "object",
  "properties": {
    "nivelUnoA": {
      "title": "nivelUnoA",
      "required": false,
      "type": "string",
      "description": "Elemento de primer nivel.",
      "default": "val1A"
    },
    "subObjetoMedio": {
      "type": "object",
      "properties": {
        "nivelDosA": {
          "title": "nivelDosA",
          "required": false,
          "type": "string",
          "description": "Elemento de segundo nivel.",
          "default": "val2A"
        },
        "subObjetoInterno": {
          "type": "object",
          "properties": {
            "nivelTresA": {
              "title": "nivelTresA",
              "required": false,
              "type": "string",
              "description": "Elemento de tercer nivel.",
              "default": "val3A"
            }
          }
        }
      }
    }
  }
}

Objetos Reutilizables

De manera similar a los arreglos, los objetos pueden definirse una vez y reefrenciarse múltiples veces.

"modeloReutilizable": {
  "type": "object",
  "properties": {
    "atributoX": {
      "title": "atributoX",
      "required": false,
      "type": "string",
      "description": "Atributo X del objeto.",
      "default": "x"
    }
  }
}

Implementación de la referencia:

"modeloReutilizado": {
  "$ref": "modeloReutilizable"
}

Manejo del Cuerpo de la Petición

El cuerpo de la petición (request body) es fundamental para enviar datos al servidor, e I/O Docs permite combinar distintos tipos de parámetros.

Configuración Básica del Payload

Un payload puede integrar arreglos, áreas de texto y referencias a objetos.

"payloadBasico": {
  "type": "object",
  "title": "payloadBasico",
  "properties": {
    "listaInterna": {
      "type": "array",
      "items": {
        "title": "listaInterna",
        "default": "",
        "type": "string",
        "description": "Arreglo dentro del payload",
        "required": true
      }
    },
    "campoTextoLargo": {
      "title": "campoTextoLargo",
      "required": false,
      "default": "Texto de ejemplo.",
      "type": "textarea",
      "description": "Área de texto en el cuerpo.",
      "location": "body"
    },
    "modeloReutilizado": {
      "$ref": "modeloReutilizable"
    }
  }
}

Tipos Mixtos en la Petición

Es posible definir un cuerpo de petición que contenga una mezcla compleja de referencias, arreglos dinámicos, áreas de texto y objetos anidados.

"peticionMixta": {
  "properties": {
    "arregloRefMixto": {
      "$ref": "arregloReutilizable"
    },
    "listaDinamica": {
      "type": "array",
      "items": {
        "title": "listaDinamica",
        "default": "defecto",
        "type": "string",
        "description": "Arreglo en el cuerpo de la petición."
      }
    },
    "notasAdicionales": {
      "title": "notasAdicionales",
      "required": false,
      "default": "Notas.",
      "type": "textarea",
      "description": "Textarea para notas en el cuerpo."
    },
    "objetoInterno": {
      "type": "object",
      "properties": {
        "propiedadA": {
          "title": "propiedadA",
          "required": false,
          "type": "string",
          "description": "",
          "default": ""
        },
        "propiedadRefB": {
          "$ref": "parametroSimple"
        }
      }
    }
  }
}

Aplicación Práctica

La configuración de I/O Docs utiliza un archivo JSON estructurado con secciones principales:

• name: Identificador del API.
• protocol: Protocolo utilizado (ej. rest).
• basePath: Ruta base para los endpoints.
• headers: Cabeceras globales de la petición.
• schemas: Definiciones de modelos de datos reutilizables.
• resources: Agrupación de endpoints y métodos disponibles.

Dentro de la sección resources, se configuran los métodos específicos, definiendo el verbo HTTP, la ruta y el cuerpo de la petición.

"envioPayload": {
  "name": "Ejemplo de envío de payload",
  "description": "Demuestra el uso de arreglos, textareas y referencias a objetos en la petición.",
  "httpMethod": "POST",
  "path": "/enviar-datos",
  "request": {
    "$ref": "payloadBasico"
  }
}