Linter de OpenAPI
OpenAPI Linter
Verifica um documento OpenAPI em busca de respostas faltando, schemas sem uso, referências que não apontam para nada e os outros defeitos que quebram geradores de código.
Confere um documento OpenAPI 3.0 ou 3.1 em busca das coisas que quebram geradores de código, fazem bibliotecas cliente mentir ou que a especificação simplesmente exige. As regras são escritas à mão e listadas na página: problemas, não preferências de estilo.
Documento OpenAPI
Solte um openapi.yaml
Lido só nesta aba.
24 achados
erroschema-array-itemscomponents.schemas.Order.items
`type: array` sem `items`.
erropath-param-undeclaredGET /orders/{orderId}
`{orderId}` no caminho não está declarado como parâmetro.
erroresponse-descriptionGET /orders/{orderId}
A resposta `200` não tem description.
erroschema-array-itemsGET /orders/{orderId} responses["200"].content["application/json"].items
`type: array` sem `items`.
erroinfo-missinginfo
Não há `info.version`. É a versão da API, não a do OpenAPI.
errooperation-id-duplicatePOST /orders/{orderId}
O operationId `getOrder` também está em GET /orders/{orderId}.
erropath-param-requiredPOST /orders/{orderId}
O parâmetro `in: path` `id` não tem `required: true`.
erropath-param-undeclaredPOST /orders/{orderId}
`{orderId}` no caminho não está declarado como parâmetro.
erropath-param-unusedPOST /orders/{orderId}
O parâmetro `in: path` `id` não aparece no caminho.
avisopath-trailing-slash/orders/
Este caminho termina em `/`.
avisoschema-unusedcomponents.schemas.Customer
Nada referencia este esquema.
avisooperation-id-missingGET /orders/
Não há operationId.
avisoresponse-errorGET /orders/
Não há resposta 4xx.
avisodescription-missingGET /orders/{orderId}
Não há summary nem description.
avisoresponse-errorGET /orders/{orderId}
Não há resposta 4xx.
avisodescription-missingPOST /orders/{orderId}
Não há summary nem description.
avisoresponse-errorPOST /orders/{orderId}
Não há resposta 4xx.
avisoresponse-successPOST /orders/{orderId}
Não há resposta 2xx nem 3xx.
notatag-missingGET /orders/
Não há etiqueta.
notatag-missingGET /orders/{orderId}
Não há etiqueta.
notaparameter-descriptionPOST /orders/{orderId}
O parâmetro `id` não tem description.
notaresponse-default-onlyPOST /orders/{orderId}
A única resposta é `default`.
notatag-missingPOST /orders/{orderId}
Não há etiqueta.
notaservers-missingservers
Não há nenhum servidor listado, então a URL base é `/`.
OpenAPI
3.0.3
Operações
3
Erros
9
Avisos
9
Notas
6
Um conjunto de regras escrito à mão. Ele pega o que faz um gerador de código tropeçar, o que faz uma biblioteca cliente mentir e o que a especificação realmente exige — problemas, não preferências. Ele não carrega conjuntos de regras do Spectral.
Para ver o que mudou entre duas versões, use Comparar mudanças do OpenAPI.
Como usar
Cole o documento
JSON ou YAML, 3.0 ou 3.1. Ele é analisado nesta aba; nada é enviado.
Resolva os erros primeiro
Cada achado carrega o id da regra e a localização exata no documento. Erros são coisas que de fato vão dar errado; avisos são coisas que normalmente vão.
Leia a lista de regras quando um achado te surpreender
Cada regra está escrita com sua severidade e o motivo de existir, então um achado do qual você discorda é pelo menos um argumento que você pode ler.
Perguntas frequentes
Ele carrega meu conjunto de regras do Spectral?
Não. Isto é um conjunto de regras fixo, escrito à mão, escolhido por problemas e não por estilo da casa. Se você tem uma configuração do Spectral, o Spectral é a ferramenta que vai respeitá-la.
Ele não lê meu arquivo Swagger 2.0.
Correto: 2.0 é um formato de documento diferente, não um 3.0 um pouco mais velho, e metade das regras não se aplicaria a ele. Converta primeiro; `swagger2openapi` é o caminho usual.
Ele não seguiu meu `$ref` externo.
Um `$ref` dentro do documento é resolvido; um que aponta para outro arquivo significaria buscar em um caminho que só a sua máquina tem. Ele é relatado como uma nota para você saber que a verificação foi incompleta, não limpa.
Por que um `operationId` ausente é um aviso?
Porque os geradores o usam para nomear a função que emitem para aquela operação. Sem um, você recebe um nome derivado do caminho e do método, que muda no momento em que o caminho muda: uma renomeação na sua API vira uma renomeação em cada cliente.
Pode receber de
JSON para JSON Schema
JSON to JSON Schema
Infere um JSON Schema de um ou vários exemplos, unindo as formas que encontra.
Validador de JSON Schema
JSON Schema Validator
Valida um documento contra um JSON Schema e informa cada falha com o caminho da instância.
curl para código
curl to Code
Converte um comando curl em fetch, axios, Python requests, Go, PHP ou PowerShell.
Comparar OpenAPI
OpenAPI Diff
Compara dois documentos OpenAPI e separa as mudanças que quebram compatibilidade das que só acrescentam.
Em seguida
Estas aceitam o que esta ferramenta produz, então o resultado pode ir direto.
curl para código
curl to Code
Converte um comando curl em fetch, axios, Python requests, Go, PHP ou PowerShell.
Validador de JSON Schema
JSON Schema Validator
Valida um documento contra um JSON Schema e informa cada falha com o caminho da instância.
Comparar OpenAPI
OpenAPI Diff
Compara dois documentos OpenAPI e separa as mudanças que quebram compatibilidade das que só acrescentam.
Formatador e validador de YAML
YAML Formatter & Validator
Reindenta YAML de forma consistente, valida e aponta os erros de tabulação e âncora que quebram os parsers.
JSON ⇄ CSV conversor
JSON ⇄ CSV
Achata JSON aninhado em colunas ou reconstrói objetos a partir de uma tabela, com uma regra de nome de coluna por caminho com pontos.
Comparar JSON
JSON Diff
Compara dois documentos JSON estruturalmente, ignorando a ordem das chaves e informando os caminhos adicionados, removidos e alterados.