OpenAPI 사양

OpenAPI 사양(OpenAPI Specification, 이전 명칭 스웨거 사양)은 웹 API를 기술, 생성, 소비 및 시각화하기 위한 기계 판독 가능 인터페이스 정의 언어에 대한 표준 사양이다. 원래 스웨거 프레임워크를 지원하기 위해 개발되었으나, 2015년에 리눅스 재단의 오픈 소스 협력 프로젝트인 OpenAPI 이니셔티브(OpenAPI Initiative)가 관리하는 별도의 프로젝트가 되었다.

OpenAPI 설명(OAD)은 도구가 코드, 문서, 테스트 케이스 등을 생성하는 데 사용할 수 있는 API의 공식적인 설명을 나타낸다.

 역사 
섬네일|리눅스 재단 산하에서 OpenAPI 사양을 개발하는 조직인 OpenAPI 이니셔티브의 로고
스웨거 개발은 2010년 초 온라인 사전 업체인 워드닉(Wordnik)에서 근무하던 토니 탐(Tony Tam)에 의해 시작되었다.

2015년 3월, 스마트베어 소프트웨어(SmartBear Software)는 워드닉의 모회사인 리버브 테크놀로지스(Reverb Technologies)로부터 오픈 소스 스웨거 API 사양을 인수했다.

2015년 11월, 스마트베어는 리눅스 재단의 후원 하에 OpenAPI 이니셔티브라는 새로운 조직에 스웨거 사양을 기부한다고 발표했다. 다른 창립 멤버 기업으로는 3스케일(3scale), 아피지(Apigee), 캐피털 원, 구글, IBM, 인튜이트, 마이크로소프트, 페이팔, 레스트릿(Restlet) 등이 포함되었다.

2016년 1월 1일, 스웨거 사양은 OpenAPI 사양(OAS)으로 명칭이 변경되었으며 새로운 깃허브 소프트웨어 저장소로 이전되었다.

2017년 7월, OpenAPI 이니셔티브는 사양의 3.0.0 버전을 출시했다.

2021년 2월, OpenAPI 이니셔티브는 3.1.0 버전을 출시했다. OpenAPI 사양 3.1.0의 주요 변경 사항으로는 JSON 스키마 어휘 정렬, 대역 외에서 등록 및 관리되는 웹훅을 기술하기 위한 새로운 최상위 요소, 표준 SPDX 식별자를 사용한 API 라이선스 식별 지원, 스키마 참조 사용과 함께 설명 허용, 컴포넌트의 재사용 가능한 라이브러리 생성을 단순화하기 위해 PathItems 객체를 선택 사항으로 변경한 것 등이 있다.

 형식의 통합 

뮤직소프트(MuleSoft)의 RESTful API Modeling Language(RAML)와 에이피어리(Apiary)의 API 블루프린트(API Blueprint)라는 두 가지 다소 유사한 기술이 당시 스웨거 사양이라 불리던 것과 비슷한 시기에 개발되었다.

두 형식의 제작자들은 나중에 OpenAPI 이니셔티브에 합류했다. 에이피어리는 2016년에, 뮤직소프트는 2017년에 합류했다. 두 곳 모두 OAS에 대한 지원을 추가했다.

 출시일 

 버전  날짜  비고3.2.02025-09-19OpenAPI 사양 3.2.0 출시3.1.22025-09-19OpenAPI 사양 3.1.2 패치 버전 출시3.1.12024-10-24OpenAPI 사양 3.1.1 패치 버전 출시 3.1.0  2021-02-15  OpenAPI 사양 3.1.0 출시3.0.42024-10-24OpenAPI 사양 3.0.4 패치 버전 출시3.0.32020-02-20OpenAPI 사양 3.0.3 패치 버전 출시3.0.22018-10-08OpenAPI 사양 3.0.2 패치 버전 출시3.0.12017-12-06OpenAPI 사양 3.0.1 패치 버전 출시 3.0.0  2017-07-26  OpenAPI 사양 3.0.0 출시 2.0  2014-09-08  스웨거 2.0 출시 1.2  2014-03-14  공식 문서의 최초 출시 1.1  2012-08-22  스웨거 1.1 출시 1.0  2011-08-10  스웨거 사양의 첫 출시

 사용법 
OAS는 다양한 애플리케이션, 라이브러리 및 도구에서 사용할 수 있는 OpenAPI 설명(OAD)의 형식을 규정한다.

애플리케이션은 OAD를 사용하여 메서드, 매개변수 및 데이터 모델의 문서를 자동으로 생성할 수 있다. 이는 문서, 클라이언트 라이브러리 및 소스 코드를 동기화된 상태로 유지하는 데 도움이 된다.

OAD를 사용하여 서버용 소스 코드 스텁을 생성할 때, 이 과정을 스캐폴딩이라고 한다.

 소프트웨어 공학 관행과의 관계 
프로그램을 먼저 코딩한 후 그 동작을 나중에 계약으로 기술하는 것과 반대로, API 계약에 먼저 합의한 후 비즈니스 로직을 프로그래밍하는 패러다임을 계약 우선(contract-first) 개발이라고 한다. 코드가 작성되기 전에 인터페이스가 결정되므로, 다운스트림 개발자는 서버 동작을 모방하여 즉시 테스트를 시작할 수 있다. 이러한 의미에서 계약 우선 개발은 쉬프트 레프트(shift-left) 테스트의 관행이기도 하다.

 특징 
OpenAPI 사양은 언어에 구애받지 않는다. OpenAPI의 선언적 리소스 사양을 사용하면, 클라이언트는 서버 구현에 대한 지식이나 서버 코드에 대한 접근 없이도 서비스를 이해하고 소비할 수 있다.

 OpenAPI와 작동하는 도구 
OpenAPI 이니셔티브는 구현체 목록을 유지 관리한다.

 연례 컨퍼런스 
OpenAPI 이니셔티브는 매년 API 사양 컨퍼런스(API Specifications Conference, ASC)를 후원한다. 이 행사는 수년 동안 운영된 API 전략 및 관행 컨퍼런스(API Strategy and Practice Conference, APIStrat)에서 유래되었으며 2016년에 OpenAPI 이니셔티브의 일부가 되었다.

 같이 보기 
 표현 상태 전송
 GRPC
 데이터 모델링

 각주 

 참고 자료 




 외부 링크 
 OpenAPI 이니셔티브 (OAI) 메인 웹사이트
 OAI 사양 웹사이트
 OAI OpenAPI 학습 웹사이트
 OAI 도구 웹사이트
 깃허브의 OpenAPI 사양
 OpenAPI 설명 디렉터리

분류:마크업 언어
분류:소프트웨어 구조
분류:API
분류:JSON