Esta página es la guía canónica para analizar documentos OpenAPI y Swagger en el navegador con DevUtilities. Pegue una especificación arriba mientras lee, o salte a un tema abajo. La validación permanece local: los documentos nunca se suben. Cuando el lint esté en verde, canalice hacia Kiota SDK Engine para la puntuación de preparación y la vista previa del comando generate.

OpenAPI Validator es un linter del lado del cliente para OpenAPI 3 y Swagger 2 en JSON/YAML. Informa VALID, VALID WITH WARNINGS o INVALID con diagnósticos con rutas para corregir bloqueadores antes de generar el SDK o importar al gateway.

Qué obtiene

• Analiza documentos OpenAPI 3.x y Swagger 2 (JSON o YAML)
• Banner de estado: VALID / VALID WITH WARNINGS / INVALID
• Comprueba claves de versión, cobertura de paths, servers y problemas estructurales comunes
• Lint solo local — seguro para specs de API internas
• Ruta directa de entrega a Kiota SDK Engine para preparación de codegen

Use esta herramienta cuando

• Necesita una comprobación rápida antes de Microsoft Kiota u otros generadores
• CI o una lista de PR exige un lint legible de la spec confirmada
• Heredó un archivo Swagger 2 y quiere advertencias de migración antes del trabajo OpenAPI 3
• operationId duplicados o $ref rotos siguen rompiendo el codegen

Prefiera una herramienta relacionada cuando

• Necesita puntuación completa de Kiota, matriz de lenguajes y constructor CLI → Kiota SDK Engine
• Solo necesita embellecer payloads JSON → JSON Formatter
• Necesita matrices de respuesta simuladas → JSON Generator

Los generadores de código (sobre todo Kiota) fallan con problemas estructurales que un vistazo informal al YAML no detecta. Analice aquí primero y luego abra Kiota SDK Engine para la preparación específica del generador.

Bloqueadores a limpiar antes del codegen

• operationId duplicado o ausente (colisiones de nombres de métodos)
• responses ausentes o vacías en códigos de éxito
• $ref inválido o colgante hacia components
• Falta la clave openapi/swagger o el objeto paths está vacío
• Referencias de schema circulares (a menudo aparecen después en Kiota)

Advertencias que puede aplazar

• Falta servers[] — los clientes pueden necesitar overrides --base-url
• Notas de migración Swagger 2 — prefiera OpenAPI 3 para APIs nuevas
• Descripciones escasas — calidad de documentación, no bloqueadores de parseo

Recorrido inicial antes de generar un SDK.

1. Pegue OpenAPI 3 o Swagger 2 como JSON o YAML en el panel de entrada.
2. Lea el estado: VALID, VALID WITH WARNINGS o INVALID.
3. Corrija cada error de la lista de diagnósticos — empiece por operationId, responses y fallos de $ref.
4. Vuelva a analizar hasta que el estado sea VALID o solo queden advertencias aceptables.
5. Canalice la spec limpia a Kiota SDK Engine para puntuación, vista previa de lenguaje y comando kiota generate.
6. Confirme el documento corregido y, opcionalmente, añada este lint como ítem de checklist de PR.

Las solicitudes de extracción fusionan ediciones OpenAPI que luego rompen la regeneración nocturna del SDK. Los revisores no pueden detectar operationId duplicados a ojo.

Cómo esta herramienta lo resuelve

1. Pegue el documento OpenAPI del PR en el validador durante la revisión.
2. Exija VALID (o solo advertencias documentadas) antes de aprobar.
3. Señale operationId duplicados y $ref rotos en el hilo de revisión con el texto del diagnóstico.
4. Tras el merge, ejecute Kiota en CI contra el mismo documento.

Una puerta de lint a velocidad humana que captura la misma clase de fallos que golpean a los generadores — sin subir la spec.

Un equipo está a punto de ejecutar kiota generate y quiere confianza de que el documento no fallará por nombres o problemas de $ref.

Cómo esta herramienta lo resuelve

1. Analice el documento aquí hasta eliminar INVALID.
2. Canalice a Kiota SDK Engine y revise la puntuación OpenAPI Readiness.
3. Corrija problemas restantes específicos de Kiota (refs circulares, estilo nullable) en los diagnósticos de Kiota.
4. Copie el comando CLI generado cuando la preparación sea aceptable.

Un flujo local de dos pasos: lint estructural → preparación Kiota → generate en su máquina.

Un JSON Swagger 2 antiguo aún alimenta un gateway. Las partes interesadas quieren OpenAPI 3 antes de adoptar Kiota.

Cómo esta herramienta lo resuelve

1. Pegue el documento Swagger 2 y anote las advertencias de migración.
2. Corrija problemas estructurales INVALID que bloquearían cualquier conversor.
3. Planifique una migración a OpenAPI 3 para funciones nuevas; mantenga Swagger 2 solo mientras esté restringido.
4. Vuelva a analizar el resultado OpenAPI 3 antes de Kiota.

Señal clara de que Swagger 2 se analiza con advertencias — prefiera OpenAPI 3 para trabajo nuevo de SDK.

Los generadores nombran métodos del cliente a partir de operationId. Los duplicados provocan colisiones.

Por qué ocurre

Dos o más operaciones comparten el mismo operationId, o falta operationId donde el generador lo exige.

Diagnóstico

Busque en el documento valores operationId repetidos. Kiota y este linter marcan colisiones: corríjalas aquí antes de abrir el motor SDK.

Correcciones

1. Asigne un operationId único a cada operación (verbo + recurso es un patrón habitual).
2. Elimine paths duplicados no usados que se copiaron al editar.
3. Si recorta para un SDK parcial, quite paths en conflicto en lugar de renombrar IDs de producción a la ligera.

Tras renombrar, vuelva a analizar y compruebe de nuevo la preparación de Kiota: los nombres de métodos en las vistas previas cambiarán.

Las operaciones sin responses usables rompen la generación tipada de clientes.

Por qué ocurre

Una operación de path omite responses, o las responses de éxito tienen content {} vacío sin schema.

Diagnóstico

Inspeccione el mapa responses de cada operación en entradas 200/201 (o default) y asegúrese de que los schemas de content se resuelvan.

Correcciones

1. Añada al menos una response de éxito con un media type application/json (o el pertinente).
2. Apunte el schema de content a components.schemas mediante $ref en lugar de dejar content vacío.
3. Documente responses de error (4xx/5xx) cuando los clientes deban manejarlas — pueden quedar advertencias si se omiten.

Los punteros $ref inválidos impiden la resolución de schemas durante el lint y el codegen.

Por qué ocurre

Un $ref apunta a un component ausente, usa un JSON Pointer incorrecto o forma un ciclo que el resolvedor no puede expandir.

Diagnóstico

Siga cada ruta $ref fallida hacia components.schemas / parameters / responses. Confirme que la clave destino existe y que la ortografía coincide.

Correcciones

1. Repare o vuelva a crear el destino del component ausente.
2. Normalice las cadenas $ref a punteros #/components/...
3. Rompa referencias circulares extrayendo DTOs superficiales (a continuación aplica la guía de refs circulares de Kiota).

Interprete el banner antes de cambiar el documento.

OpenAPI Validator y Kiota SDK Engine son complementarios. Analice la salud estructural aquí; use Kiota para la preparación del generador, la matriz de lenguajes, la selección de endpoints y la exportación del comando CLI.

• Canalice o pegue la spec limpia en Kiota SDK Engine después de VALID.
• Use los diagnósticos de Kiota para operationId duplicados, $ref circulares y problemas de estilo nullable que enfatizan los generadores.
• Copie kiota generate desde el paso Kiota Generate — la emisión de archivos sigue ejecutándose con la CLI local de Kiota.
• Mantenga ambas herramientas del lado del cliente para que los contratos de API internos nunca salgan del navegador.

• Analice en cada PR de OpenAPI antes de aprobar.
• Prefiera OpenAPI 3 para APIs nuevas; trate Swagger 2 como legado con advertencias de migración.
• Haga operationId único y estable — los renombres agitan los clientes generados.
• Siempre dé a las responses de éxito un schema resoluble.
• Elimine INVALID antes de abrir Kiota; use Kiota a continuación para la preparación específica del generador.
• No suba specs internas a lint SaaS de terceros cuando este camino local baste.