Formateador de OpenAPI que embellece y valida specs de Swagger y OpenAPI en JSON o YAML, contando rutas y operaciones.
Formateador de OpenAPI
Formateador de OpenAPI que embellece y valida specs de Swagger y OpenAPI en JSON o YAML, contando rutas y operaciones.
Esta es una herramienta local: funciona por completo en tu navegador. La spec de OpenAPI o Swagger que pegas nunca sale de tu dispositivo; nada se sube a ArrayKit ni a ningún servidor.
El formateador de OpenAPI de ArrayKit embellece y valida especificaciones de OpenAPI y Swagger en JSON o YAML, todo dentro de tu navegador. Pega una spec y analizará el documento, informará de la versión detectada (OpenAPI 3.x o Swagger 2.0), el título de la API, y contará cuántas rutas y operaciones define, luego volverá a emitir JSON o YAML limpio y con una indentación consistente. Está pensado para desarrolladores de backend y de API, redactores técnicos y equipos de plataforma que necesitan una forma rápida de ordenar un contrato editado a mano, convertir entre JSON y YAML, o comprobar la cordura de una spec antes de guardarla en control de versiones o pasarla a Swagger UI, generadores de código o una pasarela. Como la construcción de la solicitud y el análisis ocurren localmente, puedes dar formato a definiciones de API internas o no publicadas sin enviarlas a un servidor. Úsalo para detectar YAML mal formado, confirmar conteos de operaciones y estandarizar el formato en todo un repositorio.
Características
Acepta entrada en JSON y YAML: JSON es YAML válido, así que cualquiera de los dos se analiza
Detecta y etiqueta la versión de la spec: OpenAPI 3.x o Swagger 2.0
Informa del título de la API más un conteo en vivo de rutas y operaciones
Cuenta las ocho operaciones HTTP (get, put, post, delete, options, head, patch, trace)
Alterna la salida entre JSON con formato y YAML de 2 espacios
Muestra los errores de análisis con el mensaje subyacente cuando un documento está mal formado
Advierte cuando no hay ningún campo openapi o swagger presente para que las specs desconocidas destaquen
Descarga el resultado con formato como openapi.json u openapi.yaml
Cómo usar Formateador de OpenAPI / Swagger
Pega tu spec de OpenAPI o Swagger (JSON o YAML) en el panel de entrada
Elige el formato de salida con el conmutador JSON / YAML de la barra de herramientas
Lee el banner de resumen con la versión, el título, el conteo de rutas y el conteo de operaciones
Copia la spec con formato o descárgala como openapi.json u openapi.yaml
Ejemplo
Entrada
openapi: 3.0.3
info: { title: Example API, version: 1.0.0 }
paths:
/users:
get: { summary: List users, responses: { '200': { description: OK } } }
post: { summary: Create user, responses: { '201': { description: Created } } }
Salida
openapi: 3.0.3
info:
title: Example API
version: 1.0.0
paths:
/users:
get:
summary: List users
responses:
'200':
description: OK
post:
summary: Create user
responses:
'201':
description: Created
Una spec mínima de OpenAPI 3.0: el formateador informa de 'OpenAPI 3.0.3 · Example API · 1 path · 2 operations'.
Errores comunes y solución de problemas
El resumen muestra 'Unknown — no openapi/swagger field'. — Añade un campo de nivel superior openapi: 3.x.x (o swagger: '2.0'); sin él no se puede detectar la versión, aunque el documento igual se formatea.
Aparece un error de análisis de YAML, a menudo sobre una indentación incorrecta o un carácter de tabulación. — YAML es sensible a la indentación y prohíbe las tabulaciones: reemplaza las tabulaciones por espacios y alinea las claves de forma consistente, luego vuelve a pegar.
El conteo de operaciones parece menor de lo esperado. — Solo se cuentan los ocho métodos HTTP estándar; las extensiones de proveedor como x-amazon-apigateway-integration y las entradas parameters/servers no son operaciones.
'The document is empty or not an object' después de pegar. — La entrada se analizó como un escalar o null: asegúrate de haber pegado el objeto completo de la spec, no una sola cadena o un fragmento parcial.
Preguntas frecuentes
¿Qué es un formateador de OpenAPI / Swagger?
Es una herramienta que analiza una especificación de API OpenAPI 3.x o Swagger 2.0 y la vuelve a emitir como JSON o YAML limpio y con indentación consistente, a la vez que informa de la versión y del número de rutas y operaciones, para que puedas revisar y estandarizar una spec rápidamente.
¿Admite specs tanto en JSON como en YAML?
Sí. Como JSON es a su vez YAML válido, puedes pegar cualquiera de los dos formatos. Usa el conmutador JSON / YAML para elegir cómo se emite la salida con formato, lo que también te permite convertir una spec de un formato al otro.
¿Valida por completo mi spec contra el esquema de OpenAPI?
Valida que el documento se analice como JSON o YAML bien formado y detecta la versión, el título, las rutas y las operaciones. No ejecuta una validación completa de JSON Schema de cada campo, así que no señalará una propiedad requerida que falte en lo profundo de una operación.
¿Qué versiones reconoce?
Etiqueta OpenAPI 3.x mediante el campo openapi y Swagger 2.0 mediante el campo swagger. Cualquier documento sin uno de esos campos se formatea pero se marca como versión desconocida.
¿Se sube mi spec de API a algún sitio?
No. El análisis, la validación y el formato se ejecutan por completo en tu navegador. La spec que pegas nunca sale de tu dispositivo y nada se sube a ArrayKit, así que los contratos de API internos o no publicados permanecen privados.
¿Puedo descargar el resultado con formato?
Sí. La spec con formato se puede copiar o descargar como openapi.json u openapi.yaml según el formato de salida que hayas seleccionado.