표준 기반 API 개발

• Web API는 객체와 endpoint를 임의로 정의해도 빠르게 동작하게 만들 수 있음
  • 하지만 “명세(specification)”가 없으면 API의 동작, 입력/출력, 규칙이 사람/팀/언어마다 달라져 공유·협업·확장이 어려워짐
• 명세는 프로그램이 “무엇을 하는지”를 **표준 형태로 공식화(formalize)**하여 보편적으로 이해 가능하게 만듦
• 명세는 구현 방법(어떤 언어/프레임워크를 쓰는지)을 강요하지 않고, API가 제공해야 하는 것(메서드, 객체, 반환 형태)을 선언적으로 정의함
• OpenAPI Specification은 RESTful API를 표준적으로 기술하는 대표 규격이며, 설계 중심(design-first) 개발을 가능하게 함

왜 표준(명세)이 필요한가

1. 언어·프레임워크가 달라도 동일한 API 계약을 공유 가능함
   • JavaScript, Java, C#, Go 등 어떤 기술로 구현해도 명세는 동일하게 유지 가능함
   • 명세는 “어떤 endpoint가 있고, 어떤 메서드(GET/POST/PUT/PATCH/DELETE)를 지원하며, 어떤 요청/응답을 주고받는지”를 정의함
2. 클라이언트 개발과 서버 개발을 분리(decouple)하여 병렬 개발 가능함
   • 둘 다 같은 명세를 목표로 구현하면 됨
   • 서버가 완성되기 전에도 클라이언트는 명세 기반으로 데이터 바인딩과 UI 개발을 진행 가능함
3. 책임 분리가 명확해짐
   • 서버는 명세에 맞게 응답을 제공함
   • 클라이언트는 JSON을 올바르게 파싱·바인딩함
   • 문제가 생기면 어디가 잘못됐는지(명세 위반 vs UI 바인딩 오류)가 명확해짐

OpenAPI Specification (OAS)

What is the OpenAPI Specification

• RESTful API에 대한 표준 명세임
  • gRPC, GraphQL을 위한 규격이 아님
• 언어 독립적(language agnostic)이고 기계가 읽을 수 있음(machine readable)
  • YAML or JSON Format으로 작성됨
  • API의 구조를 “구성 파일/선언 형태”로 표현하는 성격이 강함
• endpoint, operation, parameters, request body, response body, status code, error handling, authentication 등을 명확하게 기술함
  • 필요하면 커스텀 확장도 가능함

Swagger와 OpenAPI의 관계