Problemas de resolución de problemas con la importación de API

Este artículo es una referencia consolidada para cada error, advertencia y comportamiento inesperado documentado en la función de documentación de la API de Document360. Úsalo para diagnosticar y resolver problemas con importaciones, autenticación, la función Pruébalo!, el renderizado y la base de conocimientos.

Errores de importación

Formato inválido – Fallido en la subida del archivo API

Cuando ocurre: Cuando una o más respuestas en tu archivo de especificación de OpenAPI falten la sección requerida content .

Por qué ocurre: Document360 aplica estrictas reglas de validación de OpenAPI. Aunque un archivo puede pasar la validación en herramientas como Swagger Editor, Document360 requiere que todas las respuestas definan explícitamente tanto el tipo de medio (por ejemplo, application/json) como una referencia de esquema bajo un content bloque. Las respuestas vacías o que hacen referencia directamente a un esquema sin envoltorio content causarán este error.

Cómo solucionarlo:

1. Abre tu archivo de especificaciones OpenAPI en un editor de texto o IDE.
2. Localiza cualquier definición de respuesta que esté vacía o que haga referencia a un esquema sin content bloque.
   Incorrecto:

   responses:
     "200": {}

Correcto:

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/YourSchema"

3. Guarda el archivo y vuelve a subirlo a Document360.
   Si el problema persiste, contacta con el equipo de soporte de Document360 .

URL inválida

Cuando ocurre: Al crear una referencia de API a partir de una URL, la URL proporcionada no puede ser obtenida ni resuelta.

Por qué ocurre: La URL puede estar mal formada, ser inaccesible desde los servidores de Document360 o apuntar a un recurso que no es una especificación válida de OpenAPI.

Cómo solucionarlo: Verifica que la URL se resuelva correctamente en un navegador o con curl. Asegúrate de que devuelva un documento válido de OpenAPI JSON o YAML. Corrige la URL e inténtalo de nuevo.

Formato de archivo no soportado

Cuando ocurre: Cuando el archivo subido no es un formato compatible.

Cómo solucionarlo: Asegúrate de que tu archivo sea uno de los siguientes: JSON, YAML o YML. Document360 soporta OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 y Postman Collections.

No se puede añadir referencia de API – archivo de especificación inválido

Mensaje de error: "No se puede añadir referencia de API. Esta operación no puede completarse. Por favor, asegúrate de haber presentado un archivo de especificaciones válido."

Cuando ocurre: Al subir un archivo de especificación YAML que ha sido copiado o exportado desde un editor de texto enriquecido o procesador de texto.

Por qué ocurre: El archivo YAML subido está malformado y no es un documento válido de OpenAPI 3.0 YAML. Esto suele ocurrir cuando el archivo ha sido copiado o exportado desde un editor de texto enriquecido, que introduce caracteres de formato como \f0\fs24 barras inversas o finales que rompen el formato YAML.

1. Valida tu archivo de especificaciones: Abre tu archivo YAML en una herramienta como Swagger Editor o un editor de código para comprobar errores o problemas de formato.
2. Busca caracteres de formato no deseados: Revisa caracteres como \f0\fs24 barras \ inversas o posteriores (especialmente en la descripción del final) que puedan haber sido introducidos durante copiar-pegar desde una fuente de texto enriquecido. Estos pueden romper el formato YAML.
3. Limpiar el archivo: Utiliza un editor de texto plano o código para eliminar cualquier carácter de formato especial. Evita usar procesadores de texto al editar o guardar archivos YAML.
4. Vuelve a subir el archivo: Después de limpiar el archivo y asegurarte de que es un YAML válido de OpenAPI 3.0, intenta subirlo de nuevo.

Resumen y etiquetas no reflejadas tras la importación

Cuando ocurre: Tras importar una especificación, los artículos finales muestran títulos incorrectos o aparecen en carpetas de categorías inesperadas.

Por qué ocurre: Los summary campos y tags se definen a nivel de camino en la especificación en lugar de dentro del objeto de operación (get, post, put, o delete). Además, el tags campo debe escribirse siempre como un array, incluso cuando solo se usa una etiqueta.

Cómo solucionarlo:

1. Abre tu archivo de especificación de OpenAPI en un editor de texto.
2. Mueve los summary campos y tags dentro de cada objeto de operación y asegúrate de tags que se escriba como un array.
   Incorrecto:

   /your-endpoint:
     summary: My Endpoint
     tags: My Category
     get:
       ...

Correcto:

   /your-endpoint:
     get:
       summary: My Endpoint
       tags: ["My Category"]
       ...

3. Guarda el archivo y reimportalo a Document360. Los artículos importados usarán el summary valor como título del artículo, y las carpetas basadas en etiquetas se crearán correctamente.
   Si el problema persiste, contacta con el equipo de soporte de Document360 .

Fallos de subida con 400 Bad Request – archivo de especificación demasiado grande

Cuando ocurre: Al subir un archivo válido de especificación OpenAPI YAML o JSON que contiene endpoints con esquemas de respuesta profundamente anidados y múltiples códigos de respuesta por endpoint.

Por qué ocurre: Aunque el archivo puede ser YAML válido y pasar validadores externos como Swagger Editor, Document360 aplica un límite interno de tamaño de artículo. Cuando un endpoint contiene esquemas de respuesta anidados ocho o más niveles en múltiples códigos de respuesta, el tamaño resultante supera este límite y no puede procesarse ni almacenarse.

Cómo solucionarlo:

1. Abre tu archivo de especificación de OpenAPI en un editor de texto o IDE.
2. Para cada endpoint, conservar solo un tipo de respuesta 201, un tipo de respuesta de la serie 400 y el tipo de respuesta por defecto. Elimina todos los códigos de respuesta adicionales.
3. Para endpoints donde la respuesta 201 por sí sola contiene esquemas profundamente anidados, conservar solo el tipo de respuesta 201 y eliminar por completo la serie 400 y los tipos de respuesta por defecto.
4. Guarda el archivo modificado y vuelve a subirlo a Document360.

i️ NOTA
Si la publicación falla tras una subida exitosa, contacta con el equipo de soporte de Document360. La publicación puede requerir ayuda en el backend debido a la limitación del tamaño del artículo.

Descripciones de etiquetas de nivel superior que no se muestran en la documentación de la API

Cuando ocurre: Las descripciones y metadatos definidos en objetos de etiqueta OpenAPI de nivel superior no se muestran en la documentación generada de la API.

Por qué ocurre: Cuando un archivo de especificación OpenAPI contiene etiquetas de nivel superior usadas para agrupar operaciones de API, Document360 convierte esas etiquetas en categorías tipo carpeta durante la importación. Las categorías de carpetas se utilizan únicamente para organizar los puntos finales y no generan páginas de contenido independientes. Como resultado, cualquier descripción o metadato definido dentro de esos objetos de etiqueta de nivel superior no se renderiza.

Solución alternativa: Añade el contexto relevante directamente a las descripciones individuales de endpoints dentro de la etiqueta, para que la información sea visible en las páginas de endpoint generadas.

¿Sigues teniendo problemas?

Si los pasos anteriores no resuelven tu problema, contacta directamente con el equipo de soporte de Document360 .

Preguntas frecuentes