OpenAPI란 무엇인가요?

OpenAPI 파일(OpenAPI 문서 또는 OpenAPI 사양이라고도 알려짐)을 사용하면 개발자가 API를 설명할 수 있습니다. 이 사양은 사용 가능한 엔드포인트, 작업 매개변수, 인증 방법, 기타 정보를 포함하여 이 API를 사용하는 방법도 설명합니다. 이러한 사양은 YAML 또는 JSON으로 작성되며 JSON 스키마는 API 내의 데이터 형식을 설명하는 데 사용됩니다.

OpenAPI는 API 소비자와 생산자 간의 문서 및 계약(API가 수행해야 하는 일을 설명하며 법적 구속력이 없음)의 역할을 합니다. 이는 기본적으로 표준화된 형식으로 지침을 제공하는 '하나의 진실 소스' 역할을 합니다.

이러한 표준화는 API 사용 및 통합을 간소화합니다. 이를 통해 사람과 컴퓨터 모두 소스 코드에 액세스하거나 API의 내부 작동을 이해할 필요 없이 주어진 API의 기능과 구조를 이해할 수 있습니다. 또한 개발자는 작성된 언어에 관계없이 API로 작업할 수 있습니다.

OpenAPI는 대화형 최신 문서를 자동화하여 일부 반복적인 문서 작업을 제거하고 문서를 최신 상태로 유지하는 데 도움이 됩니다. 또한 OpenAPI는 클라이언트 SDK를 위한 코드 생성 및 기타 상용구 코드를 사양에서 자동으로 생성하여 인적 오류를 줄이고 개발자의 작업량을 더욱 최소화할 수 있습니다.

SwaggerUI를 비롯한 OpenAPI 사양을 사용하는 도구는 대화형 인터페이스에서 API 사양을 렌더링할 수 있습니다. 이 인터페이스는 사양을 시각화하는 데 도움이 될 뿐만 아니라 테스트 및 검증 목적으로 브라우저 또는 웹 서비스에서 직접 실제 API 호출을 가능하게 합니다.

OpenAPI는 REST API가 설명되는 방식을 표준화함으로써 상호 운용성과 도구를 개선하고 API 라이프사이클 전반에 걸쳐 운영을 지원합니다. 잘 정돈되고 탄탄하게 관리된 사양서는 포괄적인 API 전략을 구현하는 데 있어 기반이 되는 도구가 될 수 있으며, 통합, 협업, 오류 방지, 그리고 보다 강력한 API 관리를 지원합니다.

전체 사양은 GitHub 에서 확인할 수 있습니다.

사실상 업계 표준인 OpenAPI는 API 개발을 위한 안전하고 자동화되고 널리 이해되는 문서를 제공합니다.

OpenAPI는 원래 개발자 Tony Tam이 만들었으며 2011년에 Swagger라는 이름으로 처음 출시되었습니다. 당시 API 사양은 지루한 업데이트가 필요한 정적 문서인 경우가 많았고 최신 버전이 아닐 때가 많았습니다. Swagger 사양에는 API 호출을 실시간으로 테스트할 수 있는 '사용해 보기' 버튼 등과 같은 API 개발의 몇 가지 혁신이 포함되어 있습니다.

Swagger는 문서화를 존재의 초점으로 삼았습니다. 이를 통해 개발자는 포스트잇처럼 소스 코드에 주석을 추가할 수 있었습니다. Swagger는 이러한 주석을 읽고 문서를 자동으로 업데이트할 수 있으므로, 지루하고 반복적인 업데이트 작업 없이 문서를 최신 상태로 유지할 수 있습니다. 또한 Swagger는 머신이 읽을 수 있는 JSON으로 API를 설명하는 형식을 도입하여 언어에 구애받지 않았습니다. 즉 백엔드 언어에 관계없이 Swagger는 범용 JSON 파일을 출력합니다.

Swagger는 2015년에 SmartBear Software에 인수되었으며, 얼마 지나지 않아 OpenAPI로 이름이 변경되었고 Linux Foundation 산하의 새로운 OpenAPI Initiative(OAI)에 기부되었습니다. 현재 버전은 OpenAPI 3.1입니다.

OpenAPI 사양은 API 구조와 구문을 정의하는 표준화되고 사람과 머신이 읽을 수 있는 문서입니다. 모든 OpenAPI 문서는 특정 구성 요소를 포함하고 동일한 기본 구조를 준수하지만, 일부 사양에는 다른 사양보다 더 많은 정보가 포함되어 있습니다. 사양에는 최소한openAPI 및info 필드와 최소 하나의path ,component 또는 webhook 필드가 포함되어야 합니다^.1

openAPI: '3.1.1'과 같이 문서에서 사용하는 OpenAPI 버전을 표시합니다.

info: API 제목 및 버전 번호, API 설명, 서비스 약관 및 연락처 정보와 같은 일반 API 메타데이터를 포함합니다. 

servers: API에 액세스할 수 있는 기본 URL 목록(스테이징 환경과 프로덕션 환경이 모두 포함될 수 있음). 이 목록에는 환경별 호스트에 대한 변수가 포함되어 있습니다.

paths: 경로 및 관련 HTTP 메서드(또는 작업(예: GET, PUT, POST))와 각 경로 항목에 대한 매개변수, 요청 본문 및 응답을 설명합니다.

components: 데이터 스키마, 매개변수, 응답, 헤더 및 보안 정의와 같은 재사용 가능한 개체를 나열합니다. 이러한 개체는 문서 전체에서 참조할 수 있습니다. 컴포넌트는 $ref로 간단히 참조됩니다. 이 전략은 API 설계를 최대한 간소화합니다. 

security: OAuth 또는 API 키와 같이 API가 사용하는 보안 체계 및 인증 메커니즘을 명시합니다. 또한 보안 체계를 전 세계적으로 또는 운영별로 적용할 수 있습니다.

tags: 작업을 구성하는 데 사용되는 상위 수준 태그 목록입니다. 태그를 사용하면 문서의 명확성을 높이는 데 도움이 될 수 있습니다(예: '사용자' 또는 '주문').

external documentation: API에 대한 가이드, 온보딩 문서 및 기타 외부 문서에 대한 링크

webhooks: API가 수신하는 인바운드 호출을 설명합니다. 

OpenAPI는 API 개발자와 소비자에게 신뢰할 수 있는 단일 소스를 제공하고 API 프로젝트에 가치와 효율성을 더하는 기능을 제공합니다.

OpenAPI는 처음에 REST API에 대한 문서화에 중점을 두고 만들어졌으며, 오늘날에도 그러한 초점은 여전히 핵심입니다. 문서는 표준화되고, 대화형이며, 실시간으로 업데이트되며, 신뢰할 수 있는 단일 소스를 갖춘 계약을 제공합니다.

OpenAPI 문서를 읽고 코드를 내보낼 수 있는 다양한 도구가 있습니다. 이러한 도구 중 하나는 OpenAPI 사양에 따라 작성된 문서를 읽는 Swagger Codegen입니다. 그런 다음, Swagger Codegen은 사람이 읽을 수 있는 최신 문서가 포함된 API 클라이언트 코드 소프트웨어 개발 키트(SDK), 서버 측 코드(스텁), 읽기 쉬운 웹페이지를 생성할 수 있습니다.

OpenAPI의 가장 혁신적인 기능 중 하나는 브라우저에서 바로 실시간 테스트와 검증을 수행할 수 있는 '사용해 보기' 버튼입니다. 무료 오픈 소스 도구인 Swagger UI는 시각적 인터페이스를 제공하며, 이를 통해 개발자는 실제 요청을 전송하여 원하는 대로 응답하도록 보장할 수 있습니다. 이 도구를 사용하면 요청이 작동하는지 즉시 확인할 수 있습니다.

OpenAPI는 일반적으로 서비스형 통합 플랫폼(iPaaS) 과 함께 사용됩니다.

iPaaS 플랫폼은 OpenAPI 사양을 사용하여 IT 에코시스템의 다양한 애플리케이션을 이해하고 연결합니다. 애플리케이션이 API를 설명하는 OpenAPI 사양을 공개하면 iPaaS 플랫폼은 이 정보를 사용하여 엔드포인트, 인증 방법 및 데이터 구조를 자동으로 검색할 수 있습니다. 이 전략을 사용하면 전자 상거래 플랫폼을 회계 소프트웨어와 연결하는 등의 통합을 더 빠르게 구축할 수 있습니다.

또한 OpenAPI를 사용하면 프론트엔드 및 백엔드 개발자가 병렬로 작업할 수 있습니다. 백엔드 팀이 데이터베이스를 구축하고 가동할 때까지 프론트엔드 팀이 기다려야 하는 상황보다는 병렬 작업을 진행하는 것이 더 바람직합니다. OpenAPI 계약을 통해 프론트엔드 팀은 실제 서버처럼 작동하는 모의 API 서버를 만들어 백엔드 개발이 완료되기 전에 테스트를 활성화하고 최적화할 수 있습니다. 

조직이 API를 개발하고 사용하는 방법을 지시하는 표준, 정책 및 관행인 API 거버넌스는 API가 불필요한 반복 없이 원활하고 일관되게 작동하도록 하는 데 필수적입니다. OpenAPI는 개발자 간의 계약 역할을 하기 때문에 거버넌스와 보안을 처음부터 적용할 수 있습니다.

트래픽 라우팅, 모니터링, 속도 제한과 같은 작업을 처리하는 API 게이트웨이를 예로 들어 보겠습니다. API 게이트웨이는 일반적으로 OpenAPI 사양을 사용하고 사양에 명시된 트래픽 제한 또는 기타 보안 조치를 적용할 수 있습니다.

이는 보안 규칙에도 동일하게 적용됩니다. OpenAPI 사양을 통해 개발자는 보안 요구 사항(예: OAuth 2.0 및 API 키 사용)을 선언할 수 있으며, 이러한 요구 사항은 다운스트림(게이트웨이 등)에 적용할 수 있습니다.  API 계약에 보안 기능을 간략하게 설명하면 개발자가 지원되지 않는 보안 체계를 도입하지 않도록 하는 데 도움이 됩니다.

OpenAPI는 여러 가지 방법으로 API 연결을 생성, 게시 및 관리하는 확장 가능한 프로세스인 API 관리를 강화할 수 있습니다. 예를 들어, OpenAPI 사양은 머신이 읽을 수 있고 표준화되어 있기 때문에 카탈로그 및 포털 소프트웨어가 자동으로 인덱싱할 수 있습니다. 이러한 표준화를 통해 조직 전체에서 API를 더 쉽게 찾고 이해할 수 있습니다. 이러한 검색 기능은 팀이 무의식적으로 중복된 API를 구축하는 것을 방지하는 데 도움이 됩니다.

또한 OpenAPI는 조직 표준을 명시적이고 시행 가능하게 만들어 일관된 관리 및 거버넌스를 지원합니다. 팀은 버전 관리 규칙, 오류 응답 형식 또는 명명 패턴과 같은 요구 사항을 사양에서 직접 또는 사양과 함께 정의할 수 있습니다. 이러한 기대치는 표준화된 형식으로 문서화되므로 새로운 API가 추가될 때 자동으로 검증할 수 있습니다. 이러한 검증을 통해 수동 검토에 대한 의존도를 줄이고 조직의 포트폴리오가 성장함에 따라 API가 일관성을 유지하도록 보장할 수 있습니다.