Gerador de esquemas de resposta JSON para OpenAPI
Infere um esquema de resposta a partir de amostras JSON e gera um caminho YAML OpenAPI 3.0.3.
Como funciona
Cola uma amostra JSON de resposta, introduz um caminho literal e escolhe GET, POST, PUT ou DELETE. O gerador infere um esquema do corpo de resposta e coloca o resultado num documento YAML OpenAPI 3.0.3.
Usa amostras representativas para mostrar as variações possíveis na resposta. Quando existem vários objetos na mesma localização de uma matriz, o gerador combina as propriedades e só marca uma propriedade como obrigatória quando está presente em cada objeto observado.
Revê os tipos inferidos e os campos obrigatórios antes de usar o YAML. Acrescenta os corpos dos pedidos, parâmetros, autenticação, respostas de erro e declarações de parâmetros de caminho. Depois valida o documento completo com um validador OpenAPI.
Usa esta ferramenta quando tens exemplos JSON, mas não um esquema de resposta. Só documenta o caminho e o método escolhidos a partir da amostra fornecida.
Passo a passo
- Cola uma amostra JSON de resposta
- Define um caminho literal e escolhe o método
- Revê e copia o esquema de resposta
Exemplo trabalhado
Para GET /api/users, cola {"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 numa matriz e dois objetos de métricas.
A saída marca user, tags e metrics como obrigatórios. Ambos os objetos de métricas contêm count, por isso também é obrigatório. score e active aparecem apenas num objeto cada, pelo que são opcionais. tags aceita uma cadeia ou um número inteiro; ambos os tipos observados são anuláveis porque a amostra também contém null.
Quando usar esta ferramenta
Usa o gerador para converter corpos JSON de resposta de exemplo num esquema OpenAPI inicial ao documentar um caminho.
É útil para organizar as formas de resposta observadas. O documento gerado continua a precisar dos detalhes de pedidos, segurança, erros e parâmetros da API.
Erros comuns
Um único objeto faz com que todas as propriedades incluídas pareçam obrigatórias. Para identificar propriedades que variam entre respostas, fornece vários objetos representativos na mesma localização de matriz.
Não trates a saída inferida como uma definição API completa. Verifica o tratamento de null, os campos opcionais, as variantes das matrizes e os caminhos literais. Acrescenta os detalhes dos pedidos e dos erros que estão fora do âmbito desta ferramenta.
Regras de inferência
Em cada localização 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 contratos durante a execução. Um exemplo não permite determinar que campos podem faltar nas respostas de produção.
Limitações e pressupostos
O resultado descreve os valores observados na amostra. Não identifica campos ausentes em todos os exemplos, não prova que um campo seja opcional em produção e não infere o tipo dos elementos de uma matriz vazia. Um valor apenas null não tem tipo inferível. Valores mistos são representados como alternativas e podem precisar de revisão face ao contrato da API.
Termos principais
- Documento OpenAPI
- Um documento OpenAPI descreve os caminhos, operações, entradas, respostas e outros detalhes de uma API num formato legível por máquinas.
- Esquema
- Um esquema descreve a estrutura e os tipos de valores esperados, como um objeto com propriedades identificadas.
- Propriedade obrigatória
- Nesta saída, obrigatório significa que a propriedade surgiu em todos os objetos observados nessa localização. Não comprova o comportamento em produção.
Comparar ferramentas relacionadas
Usa o conversor de YAML para JSON para obter JSON a partir de uma entrada YAML compatível. Usa 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 se transforma a amostra num esquema de resposta?
O gerador inspeciona todos os valores da amostra JSON. Cria propriedades de objetos, examina todos os elementos das matrizes e combina os tipos observados com anyOf quando necessário. Por exemplo, a matriz tags do exemplo contém cadeias, null e um inteiro, pelo que o esquema dos elementos permite uma cadeia anulável ou um inteiro anulável.
Como são representados null e tipos diferentes?
Os objetos passam a ser esquemas com propriedades. Uma propriedade é obrigatória quando está presente em todos os objetos observados nessa localização. Valores com tipos diferentes usam anyOf. Se for observado null e outro tipo, o esquema tipado recebe nullable: true. Um valor observado apenas como null não tem tipo inferível e o respetivo esquema fica sem restrições.
O que inclui o documento gerado?
O documento contém um caminho, o método escolhido GET, POST, PUT ou DELETE e uma resposta JSON bem sucedida com estado 200. O esquema fica em components e é referenciado pela resposta. O gerador não cria corpo de pedido, parâmetros, regras de segurança, respostas de erro nem cabeçalhos.
Posso introduzir um parâmetro de caminho, como um ID?
O caminho tem de ser literal e começar por uma barra, como /api/users. Os caminhos com chavetas são rejeitados, porque uma expressão como /api/users/{id} também precisa de um parâmetro de caminho declarado, que este gerador não acrescenta.
Gera ou valida um contrato API completo?
Não. A saída descreve o corpo de uma resposta de exemplo. Não infere esquemas de pedidos nem valida o YAML gerado segundo a especificação OpenAPI. Acrescenta as outras operações e detalhes da resposta e usa um validador OpenAPI para verificar 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.