API 세계의 공용어, OpenAPI 스키마: 한눈에 보는 개요와 역사

개발자라면 API(Application Programming Interface)라는 말을 지겹게 들었을 겁니다. 애플리케이션들이 서로 소통하고 데이터를 주고받을 수 있게 하는 약속이죠. 하지만 이 약속의 내용을 어떻게 명확하고 효율적으로 전달할 수 있을까요? 바로 이 지점에서 OpenAPI 스키마(OpenAPI Schema)가 등장합니다.

 

OpenAPI 스키마는 RESTful API를 설명하기 위한 표준 명세(Specification)입니다. 기계와 사람 모두가 쉽게 이해할 수 있는 형태로 API의 구조를 정의하죠. 마치 건물의 설계도처럼, API가 어떤 엔드포인트(Endpoint)를 가지고 있고, 각 엔드포인트는 어떤 요청(Request)을 받으며, 어떤 응답(Response)을 돌려주는지 등을 상세하게 기술합니다.

---

OpenAPI 스키마, 왜 필요할까요? 🧐

OpenAPI 스키마를 사용하면 여러 가지 이점을 얻을 수 있습니다.

• 명확한 의사소통: 프론트엔드와 백엔드 개발자, 기획자 등 프로젝트에 참여하는 모든 사람이 API에 대한 통일된 이해를 가질 수 있습니다. 이는 불필요한 오해와 재작업을 줄여줍니다.
• 자동화된 문서 생성: 스키마 정의만으로도 가독성 높은 API 문서를 자동으로 만들 수 있습니다. API가 변경될 때마다 문서를 수동으로 수정하는 번거로움이 사라지죠.
• 코드 생성: 클라이언트 SDK(Software Development Kit)나 서버의 기본 틀(Stub) 코드를 자동으로 생성하여 개발 생산성을 획기적으로 높일 수 있습니다.
• 테스트 자동화: 정의된 스키마를 기반으로 API 요청이 유효한지 검증하고 테스트 케이스를 생성하는 등 테스트 과정을 자동화할 수 있습니다.

기본적으로 OpenAPI 스키마는 YAML 또는 JSON 형식으로 작성되며, 다음과 같은 주요 요소로 구성됩니다.

• openapi: 사용된 OpenAPI 명세의 버전을 명시합니다. (예: 3.0.3)
• info: API의 제목, 설명, 버전 등 기본적인 정보를 담습니다.
• servers: API 서버의 기본 URL 정보를 정의합니다.
• paths: API의 각 엔드포인트 경로와 해당 경로에서 지원하는 HTTP 메서드(GET, POST, PUT, DELETE 등)에 대한 정보를 상세히 기술합니다.
• components: 여러 API에서 재사용될 수 있는 요소들(스키마, 파라미터, 보안 정책 등)을 정의하는 공간입니다.

---

스웨거(Swagger)에서 OpenAPI로: 진화의 역사 📜

OpenAPI 스키마의 역사는 '스웨거(Swagger)'라는 이름에서 시작됩니다.

 

1. 스웨거의 탄생 (2011년)

2011년, 'Wordnik'이라는 회사의 개발자 토니 탐(Tony Tam)은 자사의 API를 문서화하고 시각화하는 작업을 보다 쉽게 하기 위해 내부 도구로 스웨거를 개발했습니다. 이것이 바로 스웨거 명세(Swagger Specification)의 시작이었습니다. 스웨거는 직관적인 UI와 코드 생성 기능 덕분에 개발자들 사이에서 빠르게 인기를 얻었습니다.

 

2. 발전을 위한 개방, OpenAPI 이니셔티브 (2015년)

스웨거의 가능성을 본 SmartBear라는 회사가 2015년에 스웨거 프로젝트를 인수했습니다. 그리고 같은 해, SmartBear는 스웨거 명세를 더 개방적이고 표준화된 방식으로 발전시키기 위해 리눅스 재단(Linux Foundation)에 기증했습니다. 이를 계기로 구글, 마이크로소프트, IBM 등 여러 빅테크 기업들이 참여하는 **OpenAPI 이니셔티브(OpenAPI Initiative, OAI)**가 출범하게 됩니다.

 

3. OpenAPI 3.0의 등장 (2017년)

OAI는 스웨거 명세 2.0을 기반으로 대대적인 개선을 거쳐 2017년에 OpenAPI Specification 3.0을 발표했습니다. 이 때부터 '스웨거 명세'는 'OpenAPI 명세'라는 공식적인 이름으로 불리게 됩니다. OpenAPI 3.0은 기존 버전에 비해 구조가 더 간결해지고 재사용성이 향상되었으며, 여러 서버를 정의하거나 콜백(Callbacks), 링크(Links)와 같은 새로운 기능을 지원하는 등 많은 발전을 이루었습니다.

 

오늘날 '스웨거'는 OpenAPI 명세를 쉽게 작성하고 시각화하며 테스트할 수 있도록 도와주는 도구들(예: Swagger UI, Swagger Editor)을 지칭하는 브랜드 이름으로 남아있고, 'OpenAPI'는 API를 정의하는 표준 명세 그 자체를 의미하는 용어로 자리 잡았습니다.

이제 OpenAPI 스키마는 RESTful API 설계와 개발에 있어 사실상의 표준으로 기능하며, 수많은 개발자와 기업들이 효율적인 API 생태계를 구축하는 데 핵심적인 역할을 하고 있습니다.