Editor de OpenAPI
Escribe o pega una especificación OpenAPI 3.0, 3.1 o Swagger 2.0 a la izquierda y obtén documentación de la API en vivo a la derecha: endpoints agrupados por etiqueta, parámetros, esquemas de solicitud y respuesta con JSON de ejemplo generado, y una lista de Problemas con números de línea en los que puedes hacer clic. Tu borrador se guarda automáticamente en este navegador.
Última actualización:
Tu borrador se guarda automáticamente solo en este navegador (almacenamiento local) y nunca se sube. Haz clic en el enlace Editar de un endpoint para saltar a su YAML. Tab sangra con dos espacios; pulsa Esc y luego Tab para salir del editor.
Cómo usar Editor de OpenAPI
- Empieza con una plantilla (primero se carga el ejemplo Task Tracker 3.1), abre tu propio archivo .yaml/.json o pega una especificación.
- Edita a la izquierda: la documentación de la derecha se actualiza mientras escribes y los problemas se resaltan en el margen.
- Inserta fragmentos para una nueva ruta, operación, parámetro de consulta, esquema o esquema de seguridad; se colocan automáticamente en la sección correcta.
- Revisa la pestaña Problemas y haz clic en un elemento para saltar a su línea; usa Editar en cualquier endpoint para encontrar su YAML.
- Descarga la especificación terminada como YAML o JSON, o cópiala al portapapeles.
Anatomía de un documento OpenAPI
Todo documento OpenAPI 3 se construye con las mismas pocas secciones de nivel superior. Saber dónde va cada parte hace que la lista de Problemas del editor sea mucho más fácil de resolver:
| Sección | ¿Obligatoria? | Qué contiene |
|---|---|---|
openapi | Sí | La versión de la especificación como cadena, p. ej., 3.1.0 (Swagger 2.0 usa swagger: "2.0"). |
info | Sí | title y version (de tu API), y opcionalmente descripción, contacto y licencia. |
servers | No | URL base, opcionalmente con {variables} como un entorno o una región. |
paths | Sí en 3.0, opcional en 3.1 | Cada plantilla de URL (/tasks/{taskId}) con sus operaciones: get, post, put, patch, delete… |
components | No | schemas, parameters, responses, requestBodies y securitySchemes reutilizables, referenciados con $ref. |
security | No | Autenticación predeterminada para todas las operaciones; cada operación puede sobrescribirla (usa security: [] para endpoints públicos). |
tags | No | Nombres y descripciones que se usan para agrupar las operaciones en la documentación. |
Consejos para escribir especificaciones a mano
- Pon entre comillas los códigos de estado y las versiones: escribe
'200':yversion: "1.0". Sin comillas, YAML los lee como números. - Define los esquemas una sola vez: pon los modelos en
components/schemasy referéncialos, para que la solicitud, la respuesta y la documentación sean coherentes. - Usa allOf para modelos de "creación" y de "lectura": un esquema
NewTaskmásTask = allOf [NewTask, {id, createdAt}], como en la plantilla, evita duplicar campos. - Da a cada operación un operationId: los generadores de código lo usan como nombre del método, así que mantenlo único y en camelCase.
- Marca como readOnly los campos generados por el servidor (ids, marcas de tiempo) para que los clientes sepan que no deben enviarlos; el generador de ejemplos sigue la misma regla para los campos writeOnly.
- Describe los errores: añade respuestas 4XX o una respuesta de error
defaultcompartida para que los desarrolladores de clientes sepan cómo son los fallos.
¿Solo necesitas revisar un archivo existente? El validador de OpenAPI ofrece un informe completo y una descarga desreferenciada. Para explorar una especificación terminada con búsqueda y Swagger UI, usa el visor de OpenAPI.
Preguntas frecuentes
¿Dónde se guarda mi especificación?
Solo en el almacenamiento local de tu navegador en este dispositivo, así que seguirá ahí cuando vuelvas. No se sube nada a ningún servidor. Borrar los datos del sitio o usar una ventana privada elimina el borrador, así que descarga las especificaciones importantes.
¿Es lo mismo que Swagger Editor?
Cubre el mismo flujo de trabajo diario (editar YAML y ver la documentación generada y los errores lado a lado), pero es una herramienta ligera e independiente. No envía solicitudes de prueba a tu API; para eso, exporta la especificación y usa un cliente de API, o prueba el API Request Tester.
¿Debo escribir OpenAPI en YAML o en JSON?
Ambos describen exactamente el mismo documento. YAML es más fácil de leer y escribir a mano y admite comentarios; JSON es más fácil de generar y analizar con código. El editor convierte entre ellos con un clic (los comentarios no se trasladan a JSON).
¿Qué versión de OpenAPI debe usar una API nueva?
OpenAPI 3.1 es la versión actual y alinea los esquemas con JSON Schema 2020-12 (por ejemplo, type: [string, 'null'] en lugar de nullable). Usa 3.0.3 si tu generador de código o tu gateway aún no admite 3.1; Swagger 2.0 es solo para herramientas antiguas.
¿Cómo se crean las cargas útiles de ejemplo?
Para cada esquema de solicitud y respuesta, el editor crea un JSON de ejemplo a partir de los valores example, default o enum cuando existen y, si no, a partir del tipo y el formato (por ejemplo, una cadena date-time o un UUID). Las propiedades writeOnly se excluyen de los ejemplos.
¿Admite $ref y allOf?
Sí. Las referencias internas como #/components/schemas/Task se siguen en la vista previa, los esquemas allOf se combinan en una sola lista de propiedades y se enumeran las alternativas oneOf/anyOf. Los esquemas recursivos se muestran una vez con un marcador de recursión.
¿Puedo usarlo sin conexión?
Una vez cargada la página, la edición, la vista previa y la validación funcionan sin conexión. El analizador YAML se carga desde una CDN la primera vez; las especificaciones JSON funcionan aunque no pueda cargarse.
¿Se prueban todas las herramientas de FreeToolCabin para comprobar su calidad y precisión?
Sí. Cada herramienta del sitio pasa pruebas automáticas en navegadores reales para comprobar que el resultado es correcto y que no hay errores. Si encuentras un fallo o tienes una sugerencia, escríbenos a [email protected] y lo revisaremos.