Acceso y actualización de la documentación de una API importada

Cuando importa una especificación, Restorm no solo crea peticiones: conserva la documentación de la API —descripciones, modelos, esquemas de seguridad, ejemplos, enumeraciones— y la adjunta a la carpeta de variables creada por la importación.

Acceder a la documentación

La pestaña Docs de la carpeta de variables

Es la vista principal. Abra la carpeta de variables procedente de la importación: su barra de subpestañas incluye una pestaña Docs, junto a Entornos, Variables personalizadas y Notas.

La pestaña solo aparece si la carpeta proviene de una importación: una carpeta de variables que usted haya creado a mano no tiene documentación que mostrar.

Los demás accesos

Desde	Lo que obtiene
La pestaña Docs de una petición	La documentación de esa única operación, sin índice ni bloque de información general. Solo aparece si la operación se encuentra en la especificación
La pestaña Docs de una carpeta simple	La documentación limitada a las operaciones que contiene esa carpeta
La subpestaña de inicio de la carpeta de variables	La tarjeta Ver la documentación — «Explore la documentación de la API, los modelos y los endpoints»
La pantalla de bienvenida (tarjeta API)	El enlace rápido Documentación
El motor de búsqueda de la barra de título	Una vista previa de la documentación al pasar el cursor sobre un resultado

Lo que contiene la vista

De arriba abajo:

• el título de la API y su descripción;
• un bloque de información: Version, Source format (con un enlace a la URL de origen), Server (esquemas, host, ruta base), Contact, License, Terms of service, External docs;
• una sección por etiqueta, con su descripción;
• un bloque por operación: método y URL, resumen, marca de grupo, distintivo deprecated si corresponde, sección Security (tipo de esquema, flujo OAuth 2, ámbitos) y un Example payload plegable;
• las tablas Parameters y Responses (los códigos de estado están coloreados);
• Models — un grafo interactivo de los esquemas, navegable y con zoom;
• Polymorphism — las composiciones oneOf / anyOf / allOf;
• Enums — las enumeraciones, fusionadas con las de la carpeta.

Note

Los títulos de estas secciones (Models, Enums, Parameters, Responses, Security, Example payload) se muestran en inglés en todos los idiomas de la aplicación. Se reproducen aquí tal cual para que los reconozca en la pantalla.

Crear una petición desde la documentación

Cada bloque de operación tiene un botón + Add que crea una petición preconfigurada para esa operación. Es el camino más corto cuando una importación ha sido parcial o cuando una operación acaba de aparecer en la especificación.

Navegar y buscar

Un índice está anclado a la derecha —secciones Overview, Operations, Models, Enums—, plegable y redimensionable. Hacer clic en un modelo desplaza la vista hasta el grafo y centra en él el nodo correspondiente.

Atajo	Efecto
Ctrl+F / Cmd+F	Abre la búsqueda en la documentación
F3 / Enter	Coincidencia siguiente
Shift+F3 / Shift+Enter	Coincidencia anterior
Esc	Cierra la búsqueda

Un contador indica la posición dentro de los resultados.

Actualizar la documentación

Una especificación evoluciona. Restorm sabe volver a buscar el origen y aplicar el delta —documentación y peticiones— sin sobrescribir su trabajo.

Solo para las importaciones por URL

La resincronización solo está disponible si la carpeta se importó desde una URL. Una importación desde un archivo o mediante pegado no guarda ningún origen, y el botón de actualización no aparece: la subpestaña de inicio muestra entonces «Esta carpeta no se ha creado a partir de un origen importable.»

Esa URL no se puede modificar después desde la interfaz. Para cambiar de origen, vuelva a hacer una importación.

Dónde está el botón

Dos entradas, equivalentes:

1. la subpestaña de inicio de la carpeta de variables, sección Actualizaciones de la especificación, que muestra la URL, la Última importación y la Última comprobación, y contiene el botón Actualizar;
2. el clic derecho sobre la carpeta en el árbol lateral → Actualizar.

No hay comprobación automática

Restorm no vigila sus especificaciones en segundo plano y no le avisará de que hay una versión nueva disponible. La comprobación la desencadena siempre usted.

Qué ocurre

1. Aparece una ventana «Actualización de la especificación…» durante la recuperación. Las {{variables}} de la URL y de las cabeceras se resuelven, y la ruta de autenticación asociada se ejecuta previamente.
2. Restorm compara una huella del origen recuperado con la guardada en la última importación.
3. Nada ha cambiado → «La especificación de la API está actualizada.», y se acabó.
4. Algo ha cambiado (o la recuperación ha fallado) → se abre el asistente de resincronización.

El asistente

• La URL de origen se muestra en modo de solo lectura.
• Un botón permite asociar, modificar o desvincular una ruta de autenticación, y un submenú Custom headers permite añadir cabeceras fijas que se reenvían en cada actualización.
• Dos pestañas de previsualización:
  • Routes — el árbol de las operaciones encontradas en la nueva versión, con filtro y selección. Las operaciones ya presentes en su carpeta están bloqueadas y siempre marcadas; usted solo elige cuáles de las nuevas añadir;
  • Documentation — la documentación de la nueva versión, en modo de solo lectura, antes de validar.
• El botón de validación muestra el número de operaciones nuevas seleccionadas, por ejemplo Apply update (3).

Note

El asistente se muestra hoy en inglés sea cual sea el idioma de la aplicación («Refresh from source», «Apply update», pestañas «Routes» y «Documentation»). Por eso los títulos en inglés se reproducen aquí tal cual.

Qué se modifica y qué no

Este es el punto importante: la especificación tiene autoridad sobre lo que describe, usted tiene autoridad sobre el resto.

Elemento	Comportamiento
Nombre de una petición	Nunca se modifica
Método y URL	Nunca se modifican
Parámetros, cabeceras y parámetros de ruta existentes	Se conservan tal cual: valor, descripción, activación
Parámetros añadidos por la especificación	Se añaden, con el valor por defecto de la especificación o vacíos
Parámetros retirados de la especificación	Se conservan en la petición
Operación nueva	Se añade en el lugar donde la habría colocado una importación nueva (carpeta de etiqueta incluida)
Operación marcada como obsoleta por la especificación	Se señala; aparece atenuada en el árbol
Operación desaparecida de la especificación	Se señala como retirada; aparece tachada en el árbol, sigue siendo ejecutable y nunca se elimina
Documentación de API y enumeraciones	Se reemplazan por completo por la nueva versión: es lo que refresca la pestaña Docs

Nunca se elimina nada de su árbol: una operación que desaparece del origen se marca, no se borra.

Si el origen requiere autenticación

Una respuesta 401 o 403 abre el asistente con el mensaje de error mostrado tal cual (por ejemplo HTTP 401: Unauthorized). Asocie una ruta de autenticación o añada cabeceras fijas, y la previsualización se relanza.

Formatos resincronizables

Doce formatos disponen de resincronización: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC y Smithy.

Para todos los demás, una nueva importación crea un árbol nuevo. La lista completa está en Actualizar desde el origen.