# Suporte à OpenAPI Specification 3.0

Crie uma API com a OpenAPI Specification (OAS) 3.0 usando o API Contracts.

A OpenAPI Specification 3.0 vem com novos recursos, trazendo mais expressividade e produtividade para os designers de API.

Para obter mais informações sobre a OpenAPI, consulte a [Documentação do Swagger](https://swagger.io/docs/specification/about/).

## Componentes

Os componentes permitem reutilizar vários elementos em uma API. Esses elementos podem ser:

* Variáveis de caminho
* Parâmetros de consulta
* Cabeçalhos
* Respostas

## Combinações

Combinações permitem criar um novo tipo de dados combinando vários outros tipos de dados. O API Contracts permite dois tipos de combinações:

* A composição (allOf) permite agregar propriedades de esquema de diferentes esquemas. Por exemplo, você pode definir um tipo de dados Company reutilizando todas as propriedades dos tipos existentes Contact e Error. ![Exemplo de composição.](https://help.qlik.com/pt-BR/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/all_of.png)
* O polimorfismo (oneOf/anyOf) permite criar uma entidade que pode usar as propriedades de diferentes tipos de dados.
  * oneOf permite definir um tipo de dados contendo as propriedades de um dos tipos selecionados. Por exemplo, se você criar uma operação para obter informações sobre uma conta de serviço, poderá definir a resposta usando a combinação oneOf para obter todas as propriedades de Error ou todas as propriedades de ServiceAccountCount. ![Exemplo de polimorfismo.](https://help.qlik.com/pt-BR/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/oneof.png)

  * anyOf permite definir um tipo de dados que contenha as propriedades de um ou mais dos tipos selecionados. Por exemplo, você pode definir um tipo de dados nervousSystem e um tipo skeleton contendo propriedades diferentes e usar a combinação anyOf para criar um tipo de dados contendo quaisquer propriedades de qualquer um desses tipos.

    Uma combinação anyOf é válida desde que contenha todos os parâmetros necessários de pelo menos um dos tipos de dados selecionados. O exemplo abaixo usa a propriedade brain\_weight do tipo nervousSystem e as propriedades skull\_height e teeth de skeleton.

    ![Exemplo de combinação usando os tipos de dados nervousSystem e skeleton.](https://help.qlik.com/pt-BR/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/anyof.png)

Para obter mais informações sobre composição e polimorfismo, consulte [Herança e Polimorfismo](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) e [Diferença entre anyOf e oneOf](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#anyof-vs-oneof).

## Respostas

A OAS 3.0 permite definir novos tipos de respostas para suas operações:

* Intervalos de resposta: em vez de definir uma resposta como 200, você pode defini-la como 2XX, para que inclua respostas de 200 a 299.
* Respostas padrão: você pode definir uma resposta padrão a ser retornada quando uma resposta específica ou de intervalo não for definida.

As respostas definidas com um código explícito têm precedência sobre os intervalos de resposta e as respostas padrão, e os intervalos de resposta têm precedência sobre as respostas padrão. No exemplo a seguir:

* A resposta 204 está definida e tem precedência sobre as outras.
* A resposta 2XX se aplica aos códigos de resposta 200 a 203 e 205 a 299.
* A resposta padrão se aplica a todas as respostas 1XX, 3XX, 4XX e 5XX.

![Seção Respostas.](https://help.qlik.com/pt-BR/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/responses-headers-api.png)

## Segurança

A OAS 3.0 traz novos esquemas de segurança para sua API:

* Autenticação por portador
* OpenIdConnect

## Restrições

A OAS 3.0 permite indicar que algumas propriedades são somente leitura ou somente gravação.

Esta opção está disponível somente em tipos de dados e não pode ser definida em solicitações ou respostas no nível da operação.

![Exemplo de restrição.](https://help.qlik.com/pt-BR/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/designer_restrictions.png)