Todos os arquivos de especificações de API devem iniciar com letra maiúscula. Para corrigir este erro, ajuste o nome do arquivo OpenAPI, deixando-o com a primeira letra em uppercase.
A letra "v" no nome do arquivo OpenAPI, que indica a sua versão, deve estar escrita em minúscula. Para corrigir este erro, ajuste a letra "v" no título do arquivo de especificação da API, deixando-a em lowercase.
Esta verificação serve para garantir que não haja nenhum caracter do tipo "�", configurando um problema de enconding. Para corrigir, verifique seu arquivo OpenAPI e ajuste as ocorrências desses caracteres.
A especificação de API deve conter a propriedade "openapi" (não a propriedade "swagger"). Para corrigir o erro, ajuste essa propriedade.
As propriedades "url" e "variables" devem existir dentro da propriedade "servers". Para corrigir este erro, ajuste o arquivo OpenAPI de modo que exista a propriedade "servers", com suas respectivas propriedades "url" e "variables".
As URLs descritas dentro da propriedade "url" (dentro de "servers") devem cumprir as regras da seguinte expressão regular: /(?:.*)\/api\/(?:.*)\/v[0-9]*$/ . Um erro comum é a adição desnecessária de uma barra ("/") ao final da URL. Corrija a URL do servidor para que o erro pare de ser apontado.
O nome do arquivo OpenAPI deve trazer a mesma versão contida na "info" deste mesmo arquivo. Para corrigir esse erro, faça o ajuste da versão, garantindo a consistência entre o nome do arquivo e as informações contidas na "info".
Nenhum endpoint pode conter, em sua url (path), métodos HTTP. O path do endpoint deve especificar apenas o caminho que o usuário enviará a requisição.
Para cada endpoint e método HTTP, deve existir uma response para caso de sucesso (200) na requisição.
Nenhum endpoint de collection pode aceitar métodos PUT. Todas as operações de método PUT devem ter especificadas um {id}.
As propriedades "operationId" de cada um dos endpoints tem que ser únicas. Não podem existir dois endpoints com a mesma operationId.
Dentro da especificação OpenAPI não pode conter definição de schemas. Os schemas devem ser declarados em outro arquivo, como especificado na documentaçãono Guia de Implementação de Integrações.
Todas as requests e responses de todos os endpoints devem utilizar schemas externos, sendo apenas referenciados dentro do OpenAPI.
Todos os schemas referenciados no arquivo Open API devem conseguir ser derreferenciados. O algoritmo de derreferenciação acessa cada uma das referências à schemas e injeta todo o conteúdo do jsonSchema externo no objeto parseado do OpenAPI. Logo, um schema que não pôde ser derreferenciado é um schema que não conseguiu ser acessado da forma correta.
o O type {id} descrito no path do endpoint deve estar presente também no schemajsonSchema referenciado.
Caso um determinado type no jsonSchema tenha a propriedade "hasNext", obrigatoriamente este deve possuir também a propriedade "items", e vice-versa. Isso ocorre pois a propriedade "hasNext" serve para indicar que se trata de um type paginado, enquanto a propriedade "items" evidencia quais são os types a serem paginados.
Sempre que o path terminar com um {id}, este {id} deve obrigatoriamente ser required em seu schema (por ser um dado obrigatório).
É chamado de "getAll" todo path que, quando requisitado por método get, retorna uma collection. Logo, não faz sentido um endpoint de retorno de coleção não retornar uma paginação de elementos (caracterizada pela presença do hasNext).
É chamado de "getOne" todo path que, quando requisitado por método get, retorna um elemento específico ({id}). Logo, não faz sentido um endpoint de retorno único retornar uma paginação de elementos (caracterizada pela presença do hasNext).
Todos os endpoints de collection devem possuir meios para controlar a paginação. Logo, devem estar presentes os parâmetros "page" para indicar a página corrente, "pagesize" para identificar o tamanho da página e "order" para tratar a ordenação.
A API deve referenciar parâmetros padronizados para Authorization, Order, Page, PageSize, AcceptLanguage, Fields e Expand. Esses parâmetros devem ser referenciados diretamente do nosso repositório no GitHub, através do arquivo totvsApiTypesBase.json. Maiores informações podem ser encontradas no nosso Guia de Implementação de Integrações.
Todos os objetos referenciado nos "parameters" devem ser válidos. Esse erro é disparado quando um objeto em um parâmetro não consegue ser acessado de forma apropriada (geralmente por erro de digitação, causando inconsistência entre a url que faz a referência e o nome do objeto em si).
Sempre que o path terminar com um {id}, o parâmetro referente a aquele {id} deve obrigatoriamente ser required (por ser um dado obrigatório).
O OpenAPI deve utilizar responses padronizadas para casos de erros (ErrorModel, ErrorModelBase e ErrorDetail). Maiores informações podem ser encontradas no nosso Guia de Implementação de Integrações.