Esta página é o guia canônico para analisar documentos OpenAPI e Swagger no navegador com DevUtilities. Cole uma especificação acima enquanto lê, ou salte para um tópico abaixo. A validação permanece local — os documentos nunca são enviados. Quando o lint estiver verde, encaminhe para o Kiota SDK Engine para pontuação de prontidão e pré-visualização do comando generate.

OpenAPI Validator é um linter do lado do cliente para OpenAPI 3 e Swagger 2 em JSON/YAML. Relata VALID, VALID WITH WARNINGS ou INVALID com diagnósticos com caminhos para corrigir bloqueadores antes da geração de SDK ou importação no gateway.

O que você obtém

• Analisa documentos OpenAPI 3.x e Swagger 2 (JSON ou YAML)
• Banner de status: VALID / VALID WITH WARNINGS / INVALID
• Verifica chaves de versão, cobertura de paths, servers e problemas estruturais comuns
• Lint apenas local — seguro para specs de API internas
• Caminho direto de entrega ao Kiota SDK Engine para prontidão de codegen

Use esta ferramenta quando

• Você precisa de uma verificação rápida antes do Microsoft Kiota ou outros geradores
• CI ou uma checklist de PR exige um lint legível da spec confirmada
• Você herdou um arquivo Swagger 2 e quer avisos de migração antes do trabalho OpenAPI 3
• operationId duplicados ou $ref quebrados continuam quebrando o codegen

Prefira uma ferramenta relacionada quando

• Você precisa de pontuação completa do Kiota, matriz de linguagens e construtor CLI → Kiota SDK Engine
• Você só precisa embelezar payloads JSON → JSON Formatter
• Você precisa de arrays de resposta simulados → JSON Generator

Geradores de código (especialmente Kiota) falham alto em problemas estruturais que um olhar casual no YAML perde. Analise aqui primeiro e depois abra o Kiota SDK Engine para prontidão específica do gerador.

Bloqueadores a limpar antes do codegen

• operationId duplicado ou ausente (colisões de nomes de métodos)
• responses ausentes ou vazias em códigos de sucesso
• $ref inválido ou pendente em components
• Chave openapi/swagger ausente ou objeto paths vazio
• Referências de schema circulares (muitas vezes aparecem em seguida no Kiota)

Avisos que você pode adiar

• servers[] ausente — clientes podem precisar de overrides --base-url
• Notas de migração Swagger 2 — prefira OpenAPI 3 para novas APIs
• Descrições escassas — qualidade de documentação, não bloqueadores de parse

Percurso inicial antes de gerar um SDK.

1. Cole OpenAPI 3 ou Swagger 2 como JSON ou YAML no painel de entrada.
2. Leia o status: VALID, VALID WITH WARNINGS ou INVALID.
3. Corrija cada erro na lista de diagnósticos — comece por operationId, responses e falhas de $ref.
4. Reanalise até o status ser VALID ou restarem apenas avisos aceitáveis.
5. Encaminhe a spec limpa ao Kiota SDK Engine para pontuação, pré-visualização de linguagem e comando kiota generate.
6. Faça commit do documento corrigido e, opcionalmente, adicione este lint como item de checklist de PR.

Pull requests mesclam edições OpenAPI que depois quebram a regeneração noturna do SDK. Revisores não conseguem ver operationIds duplicados a olho.

Como esta ferramenta resolve isso

1. Cole o documento OpenAPI do PR no validador durante a revisão.
2. Exija VALID (ou apenas avisos documentados) antes de aprovar.
3. Aponte operationId duplicados e $ref quebrados no fio de revisão com o texto do diagnóstico.
4. Após o merge, execute o Kiota no CI contra o mesmo documento.

Um gate de lint em velocidade humana que captura a mesma classe de falhas que os geradores — sem enviar a spec.

Uma equipe está prestes a executar kiota generate e quer confiança de que o documento não falhará por nomes ou problemas de $ref.

Como esta ferramenta resolve isso

1. Analise o documento aqui até eliminar INVALID.
2. Encaminhe ao Kiota SDK Engine e revise a pontuação OpenAPI Readiness.
3. Corrija problemas restantes específicos do Kiota (refs circulares, estilo nullable) nos diagnósticos do Kiota.
4. Copie o comando CLI gerado quando a prontidão for aceitável.

Um fluxo local em duas etapas: lint estrutural → prontidão Kiota → generate na sua máquina.

Um JSON Swagger 2 antigo ainda alimenta um gateway. Stakeholders querem OpenAPI 3 antes de adotar o Kiota.

Como esta ferramenta resolve isso

1. Cole o documento Swagger 2 e anote avisos de migração.
2. Corrija problemas estruturais INVALID que bloquearíam qualquer conversor.
3. Planeje uma migração OpenAPI 3 para novos recursos; mantenha Swagger 2 apenas enquanto estiver restrito.
4. Reanalise o resultado OpenAPI 3 antes do Kiota.

Sinal claro de que Swagger 2 é analisado com avisos — prefira OpenAPI 3 para novo trabalho de SDK.

Geradores nomeiam métodos do cliente a partir de operationId. Duplicatas causam colisões.

Por que acontece

Duas ou mais operações compartilham o mesmo operationId, ou operationId está ausente onde o gerador exige.

Diagnóstico

Pesquise no documento valores operationId repetidos. Kiota e este linter marcam colisões — corrija aqui antes de abrir o motor SDK.

Correções

1. Atribua um operationId único a cada operação (verbo + recurso é um padrão comum).
2. Remova paths duplicados não usados que foram copiados durante a edição.
3. Se estiver cortando para um SDK parcial, remova paths em conflito em vez de renomear IDs de produção à toa.

Após renomear, reanalise e verifique novamente a prontidão do Kiota — os nomes dos métodos nas pré-visualizações mudarão.

Operações sem responses utilizáveis quebram a geração tipada de clientes.

Por que acontece

Uma operação de path omite responses, ou responses de sucesso têm content {} vazio sem schema.

Diagnóstico

Inspecione o mapa responses de cada operação em entradas 200/201 (ou default) e garanta que os schemas de content resolvam.

Correções

1. Adicione pelo menos uma response de sucesso com media type application/json (ou relevante).
2. Aponte o schema de content para components.schemas via $ref em vez de deixar content vazio.
3. Documente responses de erro (4xx/5xx) quando os clientes devem tratá-las — avisos podem permanecer se omitidas.

Ponteiros $ref inválidos impedem a resolução de schemas durante o lint e o codegen.

Por que acontece

Um $ref aponta para um component ausente, usa um JSON Pointer errado ou forma um ciclo que o resolvedor não consegue expandir.

Diagnóstico

Siga cada caminho $ref com falha em components.schemas / parameters / responses. Confirme que a chave de destino existe e a ortografia corresponde.

Correções

1. Repare ou recrie o destino do component ausente.
2. Normalize strings $ref para ponteiros #/components/...
3. Quebre referências circulares extraindo DTOs rasos (o guia de refs circulares do Kiota aplica-se em seguida).

Interprete o banner antes de alterar o documento.

OpenAPI Validator e Kiota SDK Engine são complementares. Analise a saúde estrutural aqui; use o Kiota para prontidão do gerador, matriz de linguagens, seleção de endpoints e exportação de comando CLI.

• Encaminhe ou cole a spec limpa no Kiota SDK Engine após VALID.
• Use diagnósticos do Kiota para operationId duplicados, $ref circulares e problemas de estilo nullable que os geradores enfatizam.
• Copie kiota generate a partir do passo Kiota Generate — a emissão de arquivos ainda corre via CLI local do Kiota.
• Mantenha ambas as ferramentas no cliente para que contratos de API internos nunca saiam do navegador.

• Analise em cada PR OpenAPI antes de aprovar.
• Prefira OpenAPI 3 para novas APIs; trate Swagger 2 como legado com avisos de migração.
• Torne operationId único e estável — renomeações agitam clientes gerados.
• Sempre dê às responses de sucesso um schema resolvível.
• Elimine INVALID antes de abrir o Kiota; use o Kiota em seguida para prontidão específica do gerador.
• Não envie specs internas para lint SaaS de terceiros quando este caminho local bastar.