Especificação Open API 3.1.0

Sumário

A especificação Open API teve a sua última versão liberada no dia 16 de fevereiro de 2021. Houve algumas mudanças, inclusive relacionadas às quebras de compatibilidade, algo que não fica claro apenas olhando o número da versão acrescida (de 3.0.0 para 3.1.0).

Neste artigo, irei apresentar mais detalhes dessas mudanças e os impactos gerados por essa nova versão da especificação com quebras de compatibilidade.

Introdução

A especificação Open API (OAS) define uma interface padrão agnóstica de linguagem de programação para desenvolvimento de APIs que utilizam como base o protocolo HTTP. Esse padrão permite que humanos e computadores descubram e entendam os recursos do serviço, sem necessidade de ler documentações extensas ou acessar diretamente o código-fonte.

Uma definição Open API pode então ser usada por ferramentas de geração de documentação para exibir detalhes da API, ferramentas de geração de código para gerar servidores e clientes em várias linguagens de programação, plataformas de teste e muitos outros casos de uso.

Versão 3.1.0

A OAS 3.1.0 traz novas funcionalidades e melhorias consideráveis. Isso faz com que em algum momento, num futuro próximo, APIs já existentes na versão 3.0.x sentirão a necessidade de atualização para essa nova versão, visando usufruir dos novos recursos. Porém, é preciso ter alguns cuidados ao realizar tal atualização, pois existem casos onde há quebra de compatibilidade.

Versionamento semântico

Até a versão 3.0.0 da OAS, seguia-se o versionamento semântico 2.0.0 como um conjunto de regras para alterações na numeração das versões. Isso foi removido na versão 3.1.0, e também foi adicionado um informativo, que deixa explícito as quebras de compatibilidade que podem ocorrer em versões menores (número do meio da versão), onde o impacto é menor em comparação ao benefício da alteração.

Logo abaixo é possível verificar a definição de versionamento anterior (3.0.0)

JSON Schema

A versão 3.1 passa a ser 100% compatível com o Draft 2020-12 do Schema JSON. Na versão 3.0, essa compatibilidade não acontecia com nenhuma versão do Draft JSON. No lugar, era utilizado um subconjunto dele, algo que limitava os recursos da especificação. Apesar dessa alteração possibilitar uma grande quantidade de recursos na especificação, ela acaba trazendo algumas quebras de compatibilidade, como:

exclusiveMaximum e exclusiveMinimum passam a não aceitar valores booleanos. Com isso, é necessário realizar a seguinte mudança:

De:

Para:

Devido à conformidade com o Schema JSON, não há mais interação entre required e readOnly/writeOnly, em relação aos requests e responses na declaração de propriedades. Sendo assim, a seguinte definição não é mais válida:

A definição de arquivos (byte, binary, base64) deixa de ser feita através da propriedade format, passando a ser declarado com contentEncoding e

De:

Para:

Campos Nulos

Na versão 3.0 da especificação Open API, foi incluído o campo nullable, onde é possível configurar como true se você quer que o valor permita ser null:

Na versão 3.1, o tipo null foi adicionado e o campo nullable foi removido da especificação:

Novas funcionalidades

Além das quebras de compatibilidade, essa nova versão traz diversas melhorias e recursos interessantes. Por exemplo, a possibilidade de ter uma especificação com apenas webhooks, pois paths deixou de ser obrigatório. Mais detalhes dessa e de outras funcionalidades podem ser acessadas através dos links de referência do artigo.

Ferramentas

Por ser algo tão recente, ainda não existem ferramentas com suporte a essa nova versão. Até a presente data (17/03/2021), editores e validadores ainda não estiveram disponíveis, como vocês podem observar pela imagem a seguir retirada do site https://openapi.tools/:

Resumo

Nesse artigo foi apresentada as principais alterações da nova versão da Open API (3.1.0). Também mostramos as alterações necessárias, visando os impactos de uma atualização devido às quebras de compatibilidade da versão. Se você deseja entender mais detalhes em relação às mudanças e os novos recursos da especificação, acompanhe os links de referência:

Referências

[Notas de liberação da versão 3.1.0]

https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0

[Notas de liberação complementares da versão candidata 3.1.0rc]

https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc1

[Documentação oficial da versão 3.1.0]

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md

[Documentação oficial da versão 3.0.0]

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

[Especificação Schema JSON]

https://json-schema.org/specification.html

[Exemplo de definição de webhook]