Editar referencias

DeveloperHub incluye un único API Editor propio para trabajar con definiciones de OpenAPI 3.0, 3.1 y 3.2, además de Swagger 2.0 heredado. Reúne un editor visual de formularios, una vista de código con resaltado de sintaxis, un modo dividido en paralelo y un linter en vivo, todo en un único espacio de trabajo, sin variantes entre las que elegir.

El editor también está disponible como herramienta gratuita en app.developerhub.io/api-editor sin iniciar sesión en DeveloperHub.

Las tres vistas

Un control segmentado en la parte superior del editor permite cambiar entre tres vistas. Tu elección se recuerda entre sesiones.

• Visual: la vista predeterminada. Un editor basado en formularios con una barra lateral izquierda que refleja tu documento OpenAPI: Overview, Servers, Security schemes, Tags, Paths, Schemas y Components. Los cambios se aplican directamente a la especificación subyacente.

• Split: formulario visual a la izquierda y código con resaltado de sintaxis a la derecha, con un separador arrastrable entre ambos. Los cambios en un lado actualizan el otro.

• Source: todo el lienzo se convierte en un editor Monaco con YAML o JSON, números de línea y subrayados de error. Un selector YAML/JSON y un botón Copy se encuentran en la parte superior del panel.

Edición en el editor visual

Elige una sección en la barra lateral izquierda; el formulario correspondiente se carga en el área principal.

El editor visual cubre toda la especificación:

• Overview: título, resumen, versión, descripción, términos, contacto, licencia (con autocompletado de identificadores SPDX en 3.1+) y documentación externa.

• Servers: URL de servidor con variables de plantilla (default, description, enum).

• Security schemes: apiKey, http, oauth2, openIdConnect y mutualTLS, además de los requisitos de seguridad predeterminados del documento.

• Tags: nombre, descripción y documentación externa de cada etiqueta.

• Paths: lista de todas las rutas y los métodos definidos en cada una. Desde aquí puedes añadir rutas o saltar a la vista de una ruta para añadir operaciones.

• Panel de operación: identificador, resumen, descripción, etiquetas, indicador de obsoleto, parámetros (query/path/header/cookie/$ref), cuerpo de la solicitud (varios tipos de medio, ejemplos), respuestas (código de estado, descripción, encabezados, contenido) y anulaciones de seguridad por operación.

• Schemas: un editor recursivo para components.schemas. Cubre objetos, arreglos, primitivos, formatos, enums, nullable, $ref, composiciones allOf/oneOf/anyOf/not y discriminator.

• Components: editores para responses, parameters, examples, requestBodies, headers, links, callbacks y pathItems.

Schemas

El editor de esquemas muestra cualquier JSON Schema, por profundo que sea, con filas de propiedades en línea, menús desplegables de tipo y formato, interruptores de obligatoriedad y navegación con un clic hacia esquemas anidados.

Renombrar un esquema actualiza su nombre en la barra lateral, pero las rutas $ref en otras partes de la especificación siguen apuntando al nombre anterior. Actualiza esas referencias manualmente.

Navegar por una especificación grande

Dos atajos facilitan moverse por definiciones grandes:

• Quick Switcher: pulsa ⌘ + K (o ⌃ + K en Windows y Linux) para abrir una paleta de búsqueda sobre todo el documento. Escribe para filtrar secciones, rutas, operaciones, esquemas y componentes, y salta directamente a uno.

• Ir a la definición: dondequiera que se use un $ref (un parámetro, respuesta, encabezado o esquema), el editor muestra la definición referenciada en línea y te da un enlace para saltar a ella. Funciona entre operaciones y componentes, así que puedes seguir una referencia hasta su origen con un clic.

Las descripciones en todo el editor visual muestran su Markdown, de modo que el formato, los enlaces y los fragmentos de código aparecen como los verán los lectores.

Deshacer / Rehacer

La barra de herramientas muestra los botones Undo y Redo siempre que edites en modo Visual o Split.

Edición en Source

Haz clic en Source para que un editor Monaco de ancho completo ocupe el lienzo. Usa el selector YAML / JSON en la parte superior del panel para cambiar de formato; el editor reserializa por ti.

Al volver a Visual se analiza tu búfer. Si el código tiene un error de sintaxis, el editor conserva el último estado válido y muestra un banner descartable con un botón Return to source para que no pierdas tu trabajo.

Vista dividida

Split muestra el formulario visual a la izquierda y el código a la derecha. El separador entre ambos es arrastrable; haz doble clic para restablecerlo al 50/50. El modelo es la fuente de verdad: las ediciones visuales se reserializan en el panel de código, y las ediciones del código se analizan de nuevo en el modelo cuando sales de Source.

Linting y panel de incidencias

El editor analiza tu especificación continuamente según la especificación OpenAPI, sin importar la vista. La etiqueta en el lado derecho de la barra de herramientas muestra el recuento actual:

• Verde ✓ 0 issues: sin problemas.

• Ámbar ! N warnings: solo advertencias.

• Rojo ! N issues: al menos un error.

Un panel en la parte inferior del editor siempre muestra un encabezado Issues. Haz clic en la etiqueta o en el chevrón del encabezado para expandirlo y ver la lista. El panel recuerda tu preferencia en localStorage y se expandirá automáticamente una vez en la primera carga si hay errores.

Filtra por All / Errors / Warnings en la parte superior. Haz clic en cualquier incidencia para saltar a la línea afectada. Si estás en Visual, el editor cambia a Source automáticamente y desplaza la línea a la vista. El modo Source también muestra las incidencias en línea como subrayados rojos y ámbar.

Agente de IA

El API Editor tiene un agente de IA integrado que edita tu especificación OpenAPI por ti. Describe lo que quieres en lenguaje natural y propone los cambios; tú los revisas antes de que se aplique nada.

Ábrelo con el botón Ask AI de la barra de herramientas del editor. El panel sugiere algunas acciones rápidas para empezar:

• Fix all issues: resuelve los errores y advertencias que encontró el linter.

• Add an endpoint: describe una ruta y una operación para añadir.

• Upgrade OpenAPI version: migra el documento a una versión más reciente de OpenAPI.

También puedes corregir una sola incidencia del linter con IA: cada fila del panel Issues tiene un botón Fix with AI que limita el agente a esa incidencia, y cuando la misma regla aparece más de una vez puedes corregir todas las apariciones a la vez.

Revisión de los cambios de la IA

El agente de IA nunca edita la especificación en silencio. Cuando propone cambios, se abren como Proposed AI changes en un diff sobre el panel de código, para que veas exactamente qué se añade o se elimina. Elige Accept all para aplicarlos o Reject para descartarlos. Las ediciones aceptadas pasan por el mismo historial de deshacer/rehacer que las tuyas, así que siempre puedes retroceder.

El agente de IA se limita a la referencia de API que estás editando. Lee la especificación actual antes de sugerir ediciones y rechaza las solicitudes que no tratan sobre esta referencia de API.

Editar una definición de API existente

Para editar una definición que ya está en tu proyecto de DeveloperHub:

• En la navegación superior del editor, abre el menú de secciones y elige la referencia de API en el grupo API Reference.

• Cuando la referencia de API haya cargado, haz clic en Edit en la esquina inferior derecha. El API Editor se abre en una pestaña nueva.

• Haz tus cambios. Cuando termines, haz clic en Save Draft en la esquina superior derecha.

Las ediciones se guardan en un borrador. Para publicar, vuelve a la referencia de API dentro del editor y haz clic en Publish.

Crear una nueva definición de API

Para empezar desde cero:

• En la navegación superior del editor, abre el menú de secciones.

• Haz clic en + New API reference.

• Elige Create from scratch. El API Editor se abre en una pestaña nueva con un documento OpenAPI 3.x vacío, listo para editar.

Para importar un archivo existente, consulta Importar referencias.

Guardar y publicar

El botón Save Draft está en la esquina superior derecha del editor. La etiqueta cambia a Saved cuando tu borrador está actualizado y vuelve a Save Draft en cuanto hay cambios sin guardar. Puedes añadir un mensaje de commit opcional antes de guardar.

Guardar almacena una revisión; se conserva cada edición. Publicar la referencia de API (desde dentro de DeveloperHub) promueve el último borrador para que sea visible para tus lectores.

Generadores

Si prefieres generar el archivo OpenAPI directamente desde el código para que se mantenga sincronizado con tu base de código, estos generadores producen especificaciones a partir del código fuente:

• Javascript: swagger-jsdoc

• Express: swagger-express

• PHP: swagger-php

• Symfony: NelmioApiDocBundle

• Django: django-rest-swagger

• Flask: flask-restplus

• Ruby On Rails: openapi-rails

• Go: go-swagger

• Spring: springfox

También puedes usar nuestra API para subir referencias de forma programática.