OAS(OpenAPI Specification) / ①

문제7) OAS(OpenAPI Specification)

 

답)

 

 

1. OpenAPI 의 공통 Spec, OAS(OpenAPI Specification) 의 개요

가. OAS(OpenAPI Specification)의 개념

• API 의 이름, 파라미터, 반환 값 등의 구문, 인증 및 인가 방법, 데이터 전달 형식 등 API 를 정확하게 호출하고 그 결과를 명확히 해석하는데 필요한 정보들을 일관된 형식으로 기술한 명세서
• RESTful 과 API 에 대한 표준, 언어에 구애받지 않는 인터페이스를 정의하여 사람과 컴퓨터가 소스 코드, 문서에 액세스하거나 네트워크 트래픽 검사를 통해 서비스의 기능을 검색하고 이해할 수 있는 명세서

 

나. OAS(OpenAPI Specification)의 특징

워크 플로우 간소화	설계, 문서 및 구현을 자동으로 동기화 및 업데이트하여 API 의 빌드 프로세스를 간소화
구속없는 빌드	다양한 클라이언트 라이브러리 및 서버 템플릿을 사용하여 원하는 기술 스택에서 API 를 개발
개방적	커뮤니티 기반 공개 사양
API 파악 용이	API 를 호출하여 결과를 해석하기 위한 필수 정보만 간결하게 포함하고 있으므로, API 의 사용방법을 파악하기가 용이
소스코드 생성 용이	시스템이 해석할 수 있는 형식으로 작성된 경우, API 명세서로부터 소스코드를 생성하는 것이 가능
통합관리	다양한 프로그래밍 언어로 API를 제공해야 하는 경우 라이브러리 및 문서를 언어별로 개별적으로 관리하지 않고 통합 관리 가능
API 동작 시험	별도의 코드 작성 없이 테스트 도구에 명세서를 올려서 API 동작 시험이 가능
시스템이 해석하기에도 용이한 XML, YAML 구문 등을 사용한 API 명세서 형식이 대두 OAS 를 적용하여 REST API 를 설계(요청 및 응답, HTTP 헤더, 쿠키, 인증방법, 에러커드 등 포함) 하여 YAML 형식으로 정의할 수 있으며, 클라이언트 구현 없이 웹 브라우저를 통해 API 호출을 시험할 수 있음

 

2. OAS(OpenAPI Specification) 의 구성도 및 기능, 구성요소

가. OAS(OpenAPI Specification)의 구성도

OAS는 Swagger 2.0 버전을 기준으로 시작되어 현재 3.0.2버전으로 비동기 API 지원, API Link 정의 추가, API 보안 강화 등 개선

 

나. OAS(OpenAPI Specification)의 주요 기능 및 구성요소

구분	기능 및 구성	설명
기능	데이터 타입	기본 데이터 형은 IETF의 JSON Schema 에 기반 포맷 정보는 문서화를 용이하게 하고, 관련 도구들이 보다 효율적으로 OAS 을 처리할 수 있도록 지원 복합 데이터 구조는 기본 데이터 형들을 포함하는 'object' 형으로 정의
	API 인증	HTTP 기본 인증, API 키를 사용한 인증, OAuth 플로우 기반 인증, OpenID Connect 기반 인증 등 지원
	디자인	코드 작성 전에 리소스 및 작업을 정의하고 API 를 디자인하기 위한 완전한 형식을 제공
	문서	시각화하여 API를 운영 및 내부 개발자와 외부 소비자가 신속하게 API 를 채택 가능
	클라이언트 및 서버생성	OAS 정의를 기반으로 서버 스텁 및 클라이언트 SDK 에 대한 기반 생성
	테스트	OAS 정의에서 테스트 케이스 생성을 자동화
	모니터	OAS 생성에 정의된 작업을 사용하여 API 모니터를 생성
	배포	AWS, IBM, Apigee 등과 같은 주요 API 게이트웨이에 의해 지원
구성요소	Open api	Open api 버전 정보 표기 (예. openapi:3.0.2)
	info	API 정보를 입력 info, description(선택사항), version
	servers	API 서버 및 기본 URL 을 지정, 프로덕션 및 샌드 박스와 같은 하나 또는 여러 서버를 정의 기능 예) server : -url; http://api.aaa.co.kr , description : ITPE API 서버
	paths	API 의 개별 엔드 포인트(경로)와 이러한 엔드 포인트에서 지원하는 HTTP 메서드(작업)를 정의 tags, parameters, request body, response codes 등 정의
	components	여러 API 에서 사용되는 공통 데이터 구조를 정의 schemas : 모델을 정의 parameters, responses : api request/response 등을 정의
	security	API 에서 사용되는 인증 방법을 설명하는데 사용 HTTP authentication, OAuth2 등 지원
OpenAPI 3.0 은 API 보안성 강화측면에서 다양한 인증방법 사용

 

3. OAS의 주요 인증방법

인증방법	설명
HTTP 기본 인증	아이디와 암호를 단순 인코딩하는 방법
API 키 인증	API 키를 HTTP 헤더, URL 쿼리 파라미터, 쿠키 등으로 설정하는 방법
OpenID cONNECT 기반 인증	구글, 페이스북, 네이버 등 신뢰할 수 있는 외부 사이트의 입증 기능을 활용한 소셜 로그인 기능을 구현한 경우 사용 OpenID Connect 서버가 Discovery 프로토콜을 지원하여야 함
OAuth 플로우 기반 인증	OAuth 2.0 을 활용한 인증 방법 Authorization Code, Implicit, Password, Client Credential 인증 지원
클라우드 서비스에 OAS 적용 시에는 성능 요건, 적용가능 버전, CORS 제한 대응 등이 필요

 

---

 

공감과 댓글은 아이티신비에게 큰 힘이 됩니다.

블로그 글이 유용하다면 블로그를 구독해주세요.♥