[TIL] Open API 와 이것저것...

🗣️ 주절주절
급하게 PoC를 하게 되어서 선임님이 API를 OpenAPI로 제공해주겠다고 하셨다!
예전에는 GraphQL로 개발하다가 이번에는 REST API 기반으로 진행하게 됐는데
나는 그동안 Open API = Swagger 라고 막연히 알고 있었다...
선임님이 옆에서 그거 다른 거임..! 하시면서 개념 주입 레쭈고

📍 OpenAPI 란

• OpenAPI(OpenAPI Specification, OAS) 는 REST/HTTP API를 어떻게 문서로 표현할지 정의한 표준 명세

쉽게 말하자면..
다른 사람들이나 프로그램이 내 서비스의 API를 정해진 규칙과 형식으로 정확하게 이해하고 사용할 수 있도록 API 구조를 문서(YAML/JSON)로 표준화한 것

✏️ OpenAPI로 정의하는 것들

예를 들어

• /users/{id} 엔드포인트가
• 어떤 HTTP 메서드(GET/POST 등)를 받고
• 어떤 Path / Query / Header / Body 파라미터를 받고
• 어떤 JSON 응답을 반환하는지
• 에러는 어떤 형식인지
• 인증 방식은 무엇인지

이런 것들을 YAML 또는 JSON 문서로 선언

paths:
  /users/{id}:
    get:
      summary: Get user
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK

⭐️ 그럼 API는 뭐야?

• API(Application Programming Interface)란 프로그램 간 약속된 인터페이스

이 기능을 쓰려면 이 주소로, 이 파라미터를 이런 타입으로 보내면, 이런 형태의 결과가 온다!
같은 호출 규칙 + 데이터 규격

즉 REST API는 HTTP라는 통신 방법 위에서 동작하는 API 형태이고,
OpenAPI는 그 REST API를 표준 형식으로 설명하는 명세다

📍IPC..?

• IPC(Inter-Process Communication) 는 서로 다른 프로세스가 통신하는 모든 방식

ex) HTTP, gRPC, Socket

그래서 HTTP API도 넓게 보면 IPC의 한 형태인 것!
서비스 A 프로세스 ↔ 서비스 B 프로세스가 HTTP로 요청/응답하면 그것도 결국 프로세스 간 통신

• 즉 OpenAPI는 HTTP 기반 IPC(=HTTP API 통신)의 계약을 표준화하는 명세

📍 Code-first vs Spec-first

설명하면서 추가로 나온 개념..!
API 계약을 어떻게 만들고 유지하느냐 에 대한 접근 방식

1️⃣ Code-first (코드 먼저)

• 서버 코드를 먼저 작성하고 그 코드에서 OpenAPI 문서를 자동 생성하거나 추출

ex) Spring + Swagger Annotation, FastAPI

2️⃣ Spec-first (명세 먼저)

• OpenAPI 명세(YAML/JSON)를 먼저 작성하고 그 명세를 기준으로 서버/클라이언트를 구현

ex) OpenAPI → Server Stub, TypeScript Client SDK 생성

😗 그래서.. OpenAPI vs Swagger 정리

• OpenAPI : API 명세 표준 (Specification)
• Swagger : OpenAPI를 다루는 도구들