# OpenAPI Specification 3.0 지원

API 계약을 사용하여 OpenAPI Specification (OAS) 3.0으로 API를 설계합니다.

OpenAPI Specification 3.0에는 새로운 기능이 추가되어 API 설계자에게 더욱 뛰어난 표현력과 생산성을 제공합니다.

OpenAPI에 대한 자세한 내용은 [Swagger 문서](https://swagger.io/docs/specification/about/)를 참조하세요.

## 구성 요소

컴포넌트를 사용하면 API 전반에서 다양한 요소를 재사용할 수 있습니다.이러한 요소는 다음과 같을 수 있습니다:

* 경로 변수
* 쿼리 매개 변수
* 헤더
* 응답

## 조합

조합을 사용하면 여러 다른 데이터 형식을 결합하여 새 데이터 형식을 만들 수 있습니다.API Contracts는 두 가지 유형의 조합을 지원합니다:

* 컴포지션(allOf)을 사용하면 서로 다른 스키마의 스키마 속성을 결합할 수 있습니다.예를 들어, 기존 유형인 Contact 및 Error의 모든 속성을 재사용하여 데이터 유형 Company를 정의할 수 있습니다.![컴포지션의 예입니다.](https://help.qlik.com/ko-KR/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/all_of.png)
* 다형성(oneOf/anyOf)을 사용하면 서로 다른 데이터 유형의 속성을 사용할 수 있는 엔터티를 만들 수 있습니다.
  * oneOf을(를) 사용하면 선택한 유형 중 하나의 속성을 포함하는 데이터 유형을 정의할 수 있습니다.예를 들어 서비스 계정에 대한 정보를 가져오는 작업을 생성하는 경우, oneOf 조합을 사용하여 Error의 모든 속성 또는 ServiceAccountCount의 모든 속성을 가져오도록 응답을 정의할 수 있습니다.![다형성의 예.](https://help.qlik.com/ko-KR/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/oneof.png)

  * anyOf을(를) 사용하면 선택한 하나 이상의 유형의 속성을 포함하는 데이터 유형을 정의할 수 있습니다.예를 들어, 서로 다른 속성을 포함하는 데이터 유형 nervousSystem과 유형 skeleton을 정의하고, anyOf 조합을 사용하여 이 두 유형 중 어느 쪽의 속성이든 포함하는 데이터 유형을 만들 수 있습니다.

    anyOf 조합은 선택한 데이터 유형 중 적어도 하나의 모든 필수 매개변수를 포함하고 있다면 유효합니다.아래 예제에서는 nervousSystem 유형의 brain\_weight 속성과 skeleton의 skull\_height 및 teeth 속성을 사용합니다.

    ![nervousSystem 및 skeleton 데이터 유형을 사용하는 조합의 예입니다.](https://help.qlik.com/ko-KR/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/anyof.png)

컴포지션 및 다형성에 대한 자세한 내용은 [상속 및 다형성](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) 및 [anyOf와 oneOf의 차이점](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#anyof-vs-oneof)을 참조하세요.

## 응답

OAS 3.0을 사용하면 작업에 대한 새로운 유형의 응답을 정의할 수 있습니다:

* 응답 범위: 200과 같은 응답을 정의하는 대신 2XX로 설정하여 200부터 299까지의 응답을 포함하도록 할 수 있습니다.
* 기본 응답: 특정 응답이나 범위 응답이 정의되지 않은 경우 반환할 기본 응답을 정의할 수 있습니다.

명시적 코드로 정의된 응답은 응답 범위 및 기본 응답보다 우선하며, 응답 범위는 기본 응답보다 우선합니다.다음 예에서는:

* 204 응답이 정의되어 있으며 다른 응답보다 우선합니다.
* 2XX 응답은 응답 코드 200~203 및 205~299에 적용됩니다.
* 기본 응답은 모든 1XX, 3XX, 4XX 및 5XX 응답에 적용됩니다.

![응답 섹션.](https://help.qlik.com/ko-KR/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/responses-headers-api.png)

## 보안

OAS 3.0은 API를 위한 새로운 보안 스키마를 제공합니다:

* Bearer 인증
* OpenIdConnect

## 제한 사항

OAS 3.0에서는 일부 속성을 읽기 전용 또는 쓰기 전용으로 지정할 수 있습니다.

이 옵션은 데이터 유형에서만 사용할 수 있으며 작업 수준의 요청 또는 응답에서는 정의할 수 없습니다.

![제한 예시.](https://help.qlik.com/ko-KR/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/designer_restrictions.png)