# Obsługa specyfikacji OpenAPI 3.0

Zaprojektuj API zgodnie ze specyfikacją OpenAPI (OAS) 3.0 przy użyciu kontraktów API.

Specyfikacja OpenAPI 3.0 wprowadza nowe funkcje, zapewniając projektantom API większą ekspresyjność i produktywność.

Więcej informacji na temat OpenAPI można znaleźć w [dokumentacji Swaggera](https://swagger.io/docs/specification/about/).

## Składniki

Komponenty umożliwiają ponowne wykorzystanie różnych elementów w całym API. Te elementy mogą być:

* Zmienne ścieżki
* Query Parameters (Parametry zapytania)
* Nagłówki
* Odpowiedzi

## Kombinacje

Kombinacje umożliwiają utworzenie nowego typu danych poprzez połączenie kilku innych typów danych. Kontrakty API obsługują dwa rodzaje kombinacji:

* Kompozycja (allOf) umożliwia agregowanie właściwości schematu z różnych schematów. Na przykład możesz zdefiniować typ danych Company, ponownie wykorzystując wszystkie właściwości z istniejących typów Contact i Error. ![Przykład kompozycji.](https://help.qlik.com/pl-PL/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/all_of.png)
* Polimorfizm (oneOf/anyOf) umożliwia utworzenie encji, która może korzystać z właściwości różnych typów danych.
  * oneOf umożliwia zdefiniowanie typu danych zawierającego właściwości jednego z wybranych typów. Na przykład jeśli utworzysz operację pobierania informacji o koncie usługi, możesz zdefiniować odpowiedź przy użyciu kombinacji oneOf, aby uzyskać albo wszystkie właściwości Error, albo wszystkie właściwości ServiceAccountCount. ![Przykład polimorfizmu.](https://help.qlik.com/pl-PL/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/oneof.png)

  * anyOf umożliwia zdefiniowanie typu danych zawierającego właściwości jednego lub kilku wybranych typów. Na przykład można zdefiniować typ danych nervousSystem i typ skeleton zawierające różne właściwości oraz użyć kombinacji anyOf, aby utworzyć typ danych zawierający dowolne właściwości z któregokolwiek z tych typów.

    Kombinacja anyOf jest prawidłowa, o ile zawiera wszystkie wymagane parametry co najmniej jednego z wybranych typów danych. Poniższy przykład używa właściwości brain\_weight z typu nervousSystem oraz właściwości skull\_height i teeth z skeleton.

    ![Przykład połączenia z wykorzystaniem typów danych nervousSystem i skeleton.](https://help.qlik.com/pl-PL/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/anyof.png)

Aby uzyskać więcej informacji na temat kompozycji i polimorfizmu, zobacz [Dziedziczenie i polimorfizm](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) oraz [Różnica między anyOf a oneOf](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#anyof-vs-oneof).

## Odpowiedzi

OAS 3.0 umożliwia zdefiniowanie nowych typów odpowiedzi dla Twoich operacji:

* Zakresy odpowiedzi: zamiast definiować odpowiedź taką jak 200, możesz ustawić ją jako 2XX, tak aby obejmowała odpowiedzi od 200 do 299.
* Odpowiedzi domyślne: możesz zdefiniować domyślną odpowiedź, która zostanie zwrócona, gdy nie zdefiniowano konkretnej odpowiedzi ani odpowiedzi dla zakresu.

Odpowiedzi zdefiniowane za pomocą jawnego kodu mają pierwszeństwo przed zakresami odpowiedzi i odpowiedziami domyślnymi, a zakresy odpowiedzi mają pierwszeństwo przed odpowiedziami domyślnymi. W poniższym przykładzie:

* Odpowiedź 204 jest zdefiniowana i ma pierwszeństwo przed pozostałymi.
* Odpowiedź 2XX dotyczy kodów odpowiedzi od 200 do 203 oraz od 205 do 299.
* Odpowiedź domyślna dotyczy wszystkich odpowiedzi 1XX, 3XX, 4XX i 5XX.

![Sekcja odpowiedzi.](https://help.qlik.com/pl-PL/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/responses-headers-api.png)

## Zabezpieczenia

OAS 3.0 wprowadza nowe schematy zabezpieczeń dla Twojego API:

* Uwierzytelnianie typu Bearer
* OpenIdConnect

## Ograniczenia

OAS 3.0 pozwala wskazać, że niektóre właściwości są tylko do odczytu lub tylko do zapisu.

Ta opcja jest dostępna wyłącznie w typach danych i nie można jej zdefiniować w żądaniach ani odpowiedziach na poziomie operacji.

![Przykład ograniczenia.](https://help.qlik.com/pl-PL/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/designer_restrictions.png)