Todos os nomes dos 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.
Verifique o encode do arquivo (Deve ser UTF-8).
A especificação de API deve estar de acordo com os padrões OpenAPI (diferente do Swagger), contendo a propriedade "openapi". Para saber mais sobre as diferenças entre especificações OpenAPI e Swagger, visite esta documentação.
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".
A URL descritas dentro da propriedade "url" (dentro de "servers") deve iniciar com o valor "{{host}}". Isso é importante para que o site consiga fazer substituições desse placeholder por ambientes para sandbox.
A URL 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".
Esse arquivo OpenAPI é referente a uma nova versão menor, porém o mesmo está apresentando quebra de compatibilidade ("breaking changes") em relação à versão menor anterior.
Mudanças permitidas:
→ Novos Endpoints
→ Novos Verbos Http
→ Novas Propriedades no Schema (Desde que a API continue funcionando apenas com as que existiam anteriormente).
Mudanças que exigem uma nova versão maior:
→ Endpoints removidos ou com assinatura alterada
→ Verbos Http removidos
→ Parâmetros obrigatórios adicionados
→ Parâmetros removidos ou renomeados
→ Propriedades do schema removidas ou renomeadas
De acordo com o versionamento semântico, somente trabalhamos com versões menores enquanto não existe quebra de contrato. Quando a quebra de contrato se faz necessária, é preciso subir uma versão maior. 2.000 -> 2.100 : Subindo versão menor 2.000 -> 3.000 : Subindo versão maior |
Quando esse erro acontece, ele apresenta um sumário completo da comparação entre as duas APIs, para ficar claro o que está ok e o que está causando essa quebra
Veja o exemplo abaixo:
========================================================================== == API CHANGE LOG == ========================================================================== Filial -------------------------------------------------------------------------- -- What's Changed -- -------------------------------------------------------------------------- - GET /Branches Return Type: - Changed 200 OK Media types: - Changed application/json BackwardCompatible: Broken compatibility isBackwardCompatible: false - changed: property: items isBackwardCompatible: false type: array isChangeRequired: false properties: isBackwardCompatible: false - add: propriedade2_6 - delete: propriedade2_3 |
A partir desse relatório, entendemos que em GET /Branches, existiu quebra de compatibilidade no retorno 200 OK.
Isso ocorreu porque a propriedade chamada "propriedade2_3" foi deletada do schema.
Atenção para o valor de "isBackwardCompatible". Sempre que for "false", aponta aonde ocorreu a quebra de contrato, enquanto, se possuir valor "true", representa uma mudança aceitável, sem comprometer a compatibilidade com a versão menor anterior.
Esse arquivo OpenAPI é referente a uma nova versão minor, porém não existiu nenhuma diferença entre esta e a versão anterior.
Qual a intenção dessa nova versão?
Apenas mudar informações nas propriedades "x-totvs" não exige subir versão, visto que são apenas para documentação |
Nenhum endpoint pode conter, em sua url (path), métodos HTTP. O path do endpoint deve especificar apenas o recurso 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 no 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 dentro do 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. Qualquer erro de estruturação do arquivo jsonSchema pode causar uma falha no processo de parsing do arquivo (processo de transformação do arquivo json em objeto). Uma referência a um link quebrado, ou um arquivo/propriedade inexistente são causas comuns do disparo desse erro.
Um erro comum é referenciar o schema para a pra branch "master", sendo que o mesmo ainda não existe remotamente antes da aprovação, "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/Ticket_1_000.json#" → ERRO O correto é apontar para o URL da branch atual: Após aprovação, essa URL será ajustada para a branch "master" automaticamente. |
O type {id} descrito no path do endpoint deve estar presente também no jsonSchema referenciado. Logo, caso haja um "/{id}" na URL, deve haver também uma propriedade "id" definida no corpo do schema, escrita exatamente igual a da URL (CaseSensitive).
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.
O ID definido em um PATH também deve estar definido dentro da propriedade “Parameters” (seja direto no path ou nos verbos HTTP).
Sempre que o path de um endpoint terminar com um {id}, o type referenciado por aquele {id} na response de sucesso (200) deve obrigatoriamente ser required no schema (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.
A propriedade "x-totvs" deve existir em todos os "paths".
A propriedade "productInformation" deve existir dentro de "x-totvs" dos "paths", e deve ser do tipo array.
Dentro da propriedade "productInformation", da "x-totvs" dos "paths", deve existir a propriedade "product".
Dentro da propriedade "productInformation", da "x-totvs" dos "paths", deve existir a propriedade "available".
Todos os produtos que forem declarados no "productInformation" da "info" do OpenAPI devem estar presentes em pelo menos um dos "x-totvs" dos "paths". Essa verificação se faz necessária pois não há sentido em se declarar um produto na "info" do OpenAPI quando não há nenhum endpoint implementado para aquele produto.
Todas as propriedades "available" dos "x-totvs" dos "paths" devem ser do tipo boolean (true ou false). Essa verificação se fez necessária pelo fato de alguns OpenAPIs estarem especificando os campos available com strings (ex. "true"/"false"), fazendo com que a informação pudesse ser interpretada de forma equivocada.
A propriedade "productInformation" do "x-totvs" da "info" deve ser um array de objetos. Além disso, a propriedade "product" deve existir dentro desta "productInformation".
Para evitar inconsistência no armazenamento e visualização de nossas APIs, a grafia do campo "segment" deve estar de acordo com padrões previamente determinados. Para saber qual a grafia correta do segmento que deseja declarar, visite a lista de referências do portal de APIs e verifique no menu lateral (sob o título "Agrupadores") os padrões de grafia aceitos.
Para evitar inconsistência no armazenamento e visualização de nossas APIs, a grafia do campo "product" deve estar de acordo com padrões previamente determinados. Para saber qual a grafia correta do produto que deseja declarar, visite a lista de referências do portal de APIs e verifique no menu lateral (sob o título "Produtos") os padrões de grafia aceitos.
Todos os produtos que forem declarados nos "productInformation" de cada um dos "paths" do OpenAPI devem estar presentes também no "x-totvs" da "info". Essa verificação se faz necessária pois sempre que um endpoint é implementado em um produto, este produto deve ser explicitado no cabeçalho da especificação de API ("info"), facilitando o acesso a informação de quem lê o arquivo OpenAPI.
O "Content-Type" definido deve ser um dos permitidos, que são os seguintes:
-audio/aac
-application/x-abiword
-application/octet-stream
-video/x-msvideo
-application/vnd.amazon.ebook
-application/x-bzip
-application/x-bzip2
-application/x-csh
-text/css
-text/csv
-text/xml
-application/msword
-application/vnd.ms-fontobject
-application/epub+zip
-image/gif
-text/html
-image/x-icon
-text/calendar
-application/java-archive
-image/jpeg
-application/javascript
-application/json
-audio/midi
-video/mpeg
-application/vnd.apple.installer+xml
-application/vnd.oasis.opendocument.presentation
-application/vnd.oasis.opendocument.spreadsheet
-application/vnd.oasis.opendocument.text
-audio/ogg
-video/ogg
-font/otf
-image/png
-application/pdf
-application/vnd.ms-powerpoint
-application/x-rar-compressed
-application/rtf
-application/x-sh
-image/svg+xml
-application/x-shockwave-flash
-application/x-tar
-image/tiff
-application/typescript
-font/ttf
-application/vnd.visio
-audio/x-wav
-audio/webm
-video/webm
-image/webp
-font/woff
-font/woff2
-application/xhtml+xml
-application/vnd.ms-excel
-application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
-application/xml
-application/vnd.mozilla.xul+xml
-application/zip
-video/3gpp
-audio/3gpp
-video/3gpp2
-audio/3gpp2
-application/x-7z-compressed
Para endpoints de arquivos binários, é obrigatório que o schema siga a seguinte estrutura (Com "type": "string" e "format":"binary") (https://swagger.io/docs/specification/describing-request-body/file-upload/)
requestBody: content: image/png: schema: type: string format: binary |
Todos os nomes dos arquivos de schema devem iniciar com letra maiúscula. Para corrigir este erro, ajuste o nome do arquivo OpenAPI, deixando-o com a primeira letra em uppercase.
O nome do arquivo de schema deve conter um "_", que servirá para separar o nome do schema de sua versão (ex. AccommodationType_1_000.json).
Por convenção, o nome do arquivo jsonSchema não deve conter a letra "v" para evidenciar a versão do schema (pois a letra "v" é utilizada apenas nos títulos dos arquivos OpenAPI, como por exemplo "JobScheduler_v1_001.json). Para corrigir este erro, ajuste o nome do arquivo, retirando a letra "v" e deixando apenas os numerais referentes a versão (ex. JobScheduler_1_000.json).
Todos os schemas referenciados no arquivo Open API devem conseguir ser parseados da forma correta (significando ser um objeto válido). Qualquer erro de estruturação do arquivo jsonSchema pode causar uma falha no processo de parsing do arquivo (processo de transformação do arquivo json em objeto).
A propriedade "x-totvs" dentro da "info" do schema deve ser um objeto. Este objeto por sua vez deve, obrigatoriamente, possuir a propriedade "productInformation", sendo esta um array.
A propriedade "available", dentro dos "x-totvs" de cada um dos types deve obrigatoriamente ser do tipo "boolean". Essa verificação se fez necessária pelo fato de alguns schemas estarem especificando os campos available com strings (ex. "true"/"false"), fazendo com que a informação pudesse ser interpretada de forma equivocada pela nosso portal de referências de APIs.
Nos schemas, caso um type esteja presente no array de "required" de um type-pai, significa que este type-filho é obrigatório. Logo, por ser obrigatório, este type-filho deve estar diponível. Para ser sinalizado como disponível, deve possuir a propriedade "available":"true" em seu "x-totvs".
A propriedade "x-totvs" deve ser um array, quando existir dentro de alguma das "properties", dentro de "definitions", nos jsonSchemas. Esse caso pode ser observado no schema AppliedMatrix_1_000.json. Porém o x-totvs pode também não ser especificado (como no schema Absence_1_000.json) e continuar dentro dos padrões.
Os "x-totvs" dos types devem possuir uma propriedade "product" (com essa grafia) para especificar qual o produto que está sendo definido naquele determinado elemento de array.
Os "x-totvs" dos types devem possuir uma propriedade "available" (com essa grafia) para especificar se o produto definido naquele determinado elemento de array está disponível ou não.
Todas as propriedades "required" dos "x-totvs" dos types devem ser do tipo boolean (true ou false). Essa verificação se fez necessária pelo fato de alguns schemas estarem especificando os campos available com strings (ex. "true"/"false"), fazendo com que a informação pudesse ser interpretada de forma equivocada.
Todas as propriedades "canUpdate" dos "x-totvs" dos types devem ser do tipo boolean (true ou false). Essa verificação se fez necessária pelo fato de alguns schemas estarem especificando os campos available com strings (ex. "true"/"false"), fazendo com que a informação pudesse ser interpretada de forma equivocada.
Não é permitida nenhuma palavra existente em propriedades "notes" que ultrapasse o limite máximo de 50 caracteres.
O único separador de palavras entendido pela UI e pelo validador é o espaço em branco.
Sendo assim, ao separar palavras utilizando pipes "|" ou ponto e virgula ";" ou qualquer outro caractere, implica que será entendido como uma única palavra.
Links costumam ser outra causa para esse erro. Favor utilizar um encurtador de URL (https://bitly.com/)
A propriedade "enum" deve ser descrita como um array de strings. Um erro comum é a inserção de números ao invés de strings no array.
Dentro das "definitions", ao existir a propriedade "required", esta deve ser descrita como um array. Os types descritos nesse array serão sinalizados como obrigatórios/requeridos.
Dentro das "definitions", ao existir a propriedade "required", cada um dos elementos deste array deve ser uma string. Os types descritos nesse array serão sinalizados como obrigatórios/requeridos.
Cada um dos elementos descritos dentro da propriedade "required" (caso haja) das "definitions", deve existir como um type nas "properties" desta definição.