Gerador de esquemas de resposta JSON para OpenAPI
Infira um esquema de resposta a partir de amostras JSON e gere um caminho YAML OpenAPI 3.0.3.
Como funciona
Cole uma amostra JSON de resposta, informe um caminho literal e escolha GET, POST, PUT ou DELETE. O gerador infere um esquema do corpo da resposta e o coloca em um documento YAML OpenAPI 3.0.3.
Use amostras representativas para mostrar as variações possíveis da resposta. Quando há vários objetos no mesmo local de uma matriz, o gerador combina as propriedades e marca uma propriedade como obrigatória somente quando ela aparece em cada objeto observado.
Revise os tipos inferidos e os campos obrigatórios antes de usar o YAML. Adicione os corpos de requisição, parâmetros, autenticação, respostas de erro e declarações de parâmetros de caminho. Depois valide o documento completo com um validador OpenAPI.
Use esta ferramenta quando houver exemplos JSON, mas não um esquema de resposta. Ela documenta somente o caminho e o método escolhidos a partir da amostra fornecida.
Passo a passo
- Cole uma amostra JSON de resposta
- Informe um caminho literal e escolha o método
- Revise e copie o esquema de resposta
Exemplo detalhado
Para GET /api/users, cole {"user":{"id":7,"name":"Ada"},"tags":["vip",null,7],"metrics":[{"count":2,"score":1.5},{"count":3,"active":true}]}. A amostra contém objetos aninhados, valores mistos em uma matriz e dois objetos de métricas.
A saída marca user, tags e metrics como obrigatórios. Os dois objetos de métricas contêm count, então ele também é obrigatório. score e active aparecem em apenas um objeto cada, por isso são opcionais. tags aceita uma string ou um inteiro; os dois tipos observados são anuláveis porque a amostra também contém null.
Quando usar esta ferramenta
Use o gerador para transformar corpos JSON de resposta de exemplo em um esquema OpenAPI inicial ao documentar um caminho.
Ele ajuda a organizar os formatos de resposta observados. O documento gerado ainda precisa dos detalhes de requisição, segurança, erros e parâmetros da API.
Erros comuns
Um único objeto faz todas as propriedades incluídas parecerem obrigatórias. Para identificar propriedades que variam entre respostas, forneça vários objetos representativos no mesmo local de uma matriz.
Não trate a saída inferida como uma definição completa de API. Confira o tratamento de null, campos opcionais, variações de matrizes e caminhos literais. Adicione os detalhes de requisição e erro que estão fora do escopo desta ferramenta.
Regras de inferência
Em cada local de objeto, chaves obrigatórias = chaves presentes em todos os objetos observados.
Para cada valor, esquema inferido = união dos tipos não nulos observados.
Quando null é observado com um tipo conhecido, esse esquema tipado é marcado como anulável.
Esta inferência usa amostras e não verifica um contrato em execução. Um exemplo não permite saber quais campos podem faltar nas respostas de produção.
Limitações e premissas
O resultado descreve os valores observados na amostra. Ele não identifica campos ausentes em todos os exemplos, não prova que um campo seja opcional em produção nem infere o tipo dos itens de uma matriz vazia. Um valor observado apenas como null não tem tipo inferível. Valores mistos são representados como alternativas e podem precisar de revisão conforme o contrato da API.
Termos principais
- Documento OpenAPI
- Um documento OpenAPI descreve os caminhos, operações, entradas, respostas e outros detalhes de uma API em um formato legível por máquinas.
- Esquema
- Um esquema descreve a estrutura e os tipos de valores esperados, como um objeto com propriedades nomeadas.
- Propriedade obrigatória
- Nesta saída, obrigatório significa que a propriedade apareceu em todos os objetos observados naquele local. Isso não comprova o comportamento em produção.
Comparar ferramentas relacionadas
Use o conversor de YAML para JSON para obter JSON de uma entrada YAML compatível. Use SQL para TypeScript para obter tipos TypeScript de uma definição de tabela. Esta ferramenta infere um esquema de resposta a partir de amostras JSON.
O gerador de dados simulados para API cria linhas a partir de um objeto JSON de exemplo. Esta ferramenta infere um esquema de resposta a partir de uma amostra JSON e não gera dados simulados.
Perguntas frequentes
Como a amostra se transforma em um esquema de resposta?
O gerador inspeciona todos os valores da amostra JSON. Ele cria propriedades de objetos, examina todos os itens das matrizes e combina os tipos observados com anyOf quando necessário. Por exemplo, a matriz tags do exemplo contém strings, null e um inteiro, então o esquema dos itens permite uma string anulável ou um inteiro anulável.
Como null e tipos diferentes são representados?
Objetos viram esquemas com propriedades. Uma propriedade é obrigatória quando está presente em todos os objetos observados naquele local. Valores com tipos observados diferentes usam anyOf. Se null e outro tipo forem observados, o esquema tipado recebe nullable: true. Um valor observado apenas como null não tem tipo inferível e seu esquema fica sem restrições.
O que o documento gerado inclui?
O documento contém um caminho, o método escolhido GET, POST, PUT ou DELETE e uma resposta JSON de sucesso com status 200. O esquema fica em components e é referenciado pela resposta. O gerador não cria corpo de requisição, parâmetros, regras de segurança, respostas de erro ou cabeçalhos.
Posso informar um parâmetro de caminho, como um ID?
O caminho precisa ser literal e começar com uma barra, como /api/users. Caminhos com chaves são rejeitados porque um modelo como /api/users/{id} também precisa de um parâmetro de caminho declarado, que este gerador não adiciona.
Ele gera ou valida um contrato de API completo?
Não. A saída descreve o corpo de uma resposta de exemplo. Ela não infere esquemas de requisição nem valida o YAML gerado segundo a especificação OpenAPI. Adicione as outras operações e detalhes da resposta e use um validador OpenAPI para conferir o documento completo.
Ferramentas relacionadas
O conversor de YAML para JSON converte entradas YAML compatíveis para JSON. SQL para TypeScript obtém declarações de tipos a partir de estruturas SQL. O gerador de dados simulados para API cria linhas a partir de um objeto JSON de exemplo. Esta ferramenta infere um esquema de resposta a partir de amostras JSON.