Open Api Specification

※본문은 다음 문서를 읽으며 기억할만한 용어를 정리한 글이다.

https://swagger.io/specification/

 

 

소개

• language-agnostic interface to HTTP API : HTTP API의 인터페이스에 맞춰 언어에 상관없이 적용가능함
• agnostic : it에서는 다양한 환경에서 일정한 표준에 맞추거나 적용할 수 있는 것을 의미한다.
• 장점
  • API 기반으로 자동생성 
  • api 스펙 변경시 자동반영 (빌드시점에 확인하여 런타임에 실행된다)
  • 서버 코드 자동 생성으로 서버 개발이 완료되지않아도 예시 응답을 받을 수 있음
  • 응답 인터페이스 자동 생성 => 타입정의 오류 줄어듬

 

구성요소

path, components, webhooks

 

Path Templating

• delemited by curly braces({}) : 중괄호로 구분한다. 
• URL path parameter 표시
• operation : 운영
• 예외 경우 : ACL Access Control List) constraints
  참고 : https://itglobal.com/company/glossary/access-control-list/

Access Control List (ACL): what is it, how it works

 

• non-backward compatible : 이전 버전 호환불가 == backward incompatible
• backward compatible : 이전 버전 호환가능 

 

 

 

Format

- JSON object 로 주로 작성됨 (YAML ⊃ JSON )
  참고 : https://www.redhat.com/ko/topics/automation/what-is-yaml

YAML이란? 데이터 직렬화와 구성 파일 작성을 위한 가이드

• 구성 : fixed fields, patterned fields
• OpenAPI doc에 yaml 또는 json으로 API가 정의 되었어도, request / response body나 content는 JSON이나 YAML일 필요없음
• doc은 단일 또는 연결된 여러 doc으로 구성할 수 있다. 단, 루트파일 명칭은 openapi.json / openapi.yml 권장

 

Words

1. occationally : 때때로
2. schema : 개요
3. round-trip : 왕복
4. self-contained : 독립된 <-> composite :  복합