193. 오픈 API 규격 사양 (OpenAPI Specification / Swagger)

⚠️ 이 문서는 마이크로서비스(MSA) 수백 개가 각자 API를 열고 통신할 때 발생하는 "이 API는 어떤 파라미터를 보내면 무슨 JSON으로 대답해 주나요?"라는 끝없는 개발자 간의 의사소통 병목과 엑셀 문서 수작업의 고통을 멸망시키기 위해, **API의 명세(Specification)를 기계가 읽을 수 있는 언어(YAML/JSON)로 통일하고 명세서를 자동 생성해 주는 글로벌 표준 규격인 'OpenAPI Specification(OAS)'**을 다룹니다.

핵심 인사이트 (3줄 요약)

  1. 본질: "/users/123으로 GET 요청을 보내면 {"name": "홍길동"}이 200 OK 상태 코드로 떨어진다"는 식당의 메뉴판(API 명세서)을, 사람이 엑셀로 치는 것이 아니라 기계(봇)가 읽어 들일 수 있는 국제 표준 문법(YAML/JSON)으로 정의한 설계 도면이다.
  2. 가치: 이 도면만 던져주면, 프론트엔드 개발자는 백엔드 서버가 완성되기도 전에 자동으로 튀어나온 임시 응답(Mock)을 보고 미리 화면을 개발할 수 있으며, 클라이언트 호출 소스코드(SDK)조차 1초 만에 자동 생성(Code Generation)되는 마법이 펼쳐진다.
  3. 기술 체계: 과거 **'Swagger(스웨거)'**라는 이름으로 유명했으며 3.0 버전부터 'OpenAPI Specification(OAS)'으로 이름이 바뀌어 리눅스 파운데이션 산하의 오픈 표준이 되었다. 코드 위에 주석(Annotation)만 달아주면 명세서 웹페이지를 화려하게 자동 출력해 주는 생태계를 이끌고 있다.

Ⅰ. 엑셀(Excel) API 명세서의 비극: 낡고 썩은 문서들

사람이 손으로 문서를 쓰면 그 문서는 1분 만에 거짓말쟁이가 된다.

  1. 동기화의 실패 (Out of Sync):
    • 과거에는 백엔드 개발자가 API를 짜면, 그 스펙(파라미터 이름, 필수 여부, 리턴 값)을 워드나 엑셀 파일에 예쁘게 적어서 프론트엔드 개발자에게 이메일로 줬다.
    • 3일 뒤, 백엔드 개발자가 로직을 고치면서 변수명을 userId에서 userNo로 슬쩍 바꿨는데, 엑셀 문서를 업데이트하는 것을 깜빡했다.
  2. 커뮤니케이션 지옥 (Silo):
    • 프론트엔드 개발자는 낡은 엑셀 문서만 보고 userId로 찔렀다가 서버가 500 에러를 뱉어내자 3시간 동안 디버깅을 하다가 멱살을 잡으러 백엔드 팀으로 쳐들어간다.
  3. 해결책: 문서와 코드의 융합 (Code First):
    • OAS의 핵심 사상은 "문서를 따로 만들지 마라. 네가 짠 진짜 자바/파이썬 소스코드의 변수와 주석(Annotation)을 기계가 읽어서, 소스코드와 100% 일치하는 명세서 웹페이지를 실시간으로 자동으로 찍어내게 하라"는 것이다.

📢 섹션 요약 비유: 식당 메뉴판(API 명세서)을 엑셀로 적어두면, 주방장(백엔드)이 오늘부터 굴소스를 빼기로 레시피(코드)를 바꿨는데 홀 직원(프론트엔드)이 메뉴판 수정을 깜빡해 손님(클라이언트)이 알레르기 사고를 겪습니다. OAS는 주방의 요리 재료통(소스코드)에 바코드를 붙여놓으면 홀의 전자 메뉴판이 실시간으로 100% 동기화되어 자동으로 바뀌는 기적의 스마트 식당 시스템입니다.

Ⅱ. OpenAPI Specification의 구조와 Swagger UI

기계도 읽고 사람도 예쁘게 볼 수 있는 이중 마법이다.

  1. OAS 문서 (YAML / JSON 포맷):
    • OAS 규격은 생각보다 멍청할 정도로 단순한 텍스트 파일이다.
    paths:
  /users/{id}:
    get:
      summary: "특정 사용자 조회"
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema: { type: "integer" }
      responses:
        '200':
          description: "조회 성공"
    • 이 규칙에 맞춰 텍스트를 써두면, 전 세계의 모든 API 테스트 도구(Postman 등)가 이 파일을 먹고 해석할 수 있다.
  2. Swagger UI (화면 자동 렌더링):
    • 저 못생긴 YAML 텍스트 파일을 사람 눈에 보기 좋은 '화려한 웹페이지'로 바꿔주는 가장 유명한 렌더링 도구가 바로 Swagger UI다.
    • 브라우저에 접속하면 쫙 펼쳐진 API 목록이 보이고, 화면에 있는 [Try it out] 버튼을 누르면 굳이 별도의 테스트 툴을 켜지 않아도 웹페이지 안에서 즉시 백엔드 서버로 실제 API를 날려보고 응답 결과를 구경할 수 있다.

📢 섹션 요약 비유: OAS(YAML 텍스트)가 건물의 뼈대를 설명하는 흑백 '도면 기호(기계어)'라면, Swagger UI는 그 도면을 3D 모델링 프로그램에 넣어서 고객들이 직접 마우스로 문(API)을 열고 닫으며 집 구경을 해볼 수 있게(Try it out) 만들어주는 눈 호강 '모델하우스 화면'입니다.

Ⅲ. 계약 주도 개발 (Design First)과 1초 자동 코딩

요즘 1류 개발팀들은 코드를 짜기 전에 '계약(OAS)'부터 먼저 맺는다.

  1. Design First (API 우선 설계):
    • 과거(Code First)에는 백엔드가 다 만들어져야 프론트가 일을 시작할 수 있었다 (병목).
    • 이제는 기획이 떨어지면 양 팀이 모여, 코드는 단 1줄도 안 짠 채 OAS 파일(YAML)에 "우리는 이렇게 데이터를 주고받을 것이다"라고 껍데기(계약서)만 먼저 합의해서 작성한다.
  2. 프론트엔드의 독립 (Mock Server):
    • 이 OAS 계약서 파일을 'Mock Server(가짜 서버)' 프로그램에 밀어 넣으면, 백엔드가 1도 안 만들어졌는데도 200 OK 응답과 가짜 데이터를 뱉어내는 훌륭한 API 서버가 1초 만에 뚝딱 띄워진다. 프론트엔드 개발자는 쉴 틈 없이 즉각 화면 개발에 착수한다 (속도전의 극의).
  3. 클라이언트 코드 자동 생성 (Swagger Codegen):
    • 프론트 앱(React, iOS)에서 백엔드를 찌르려면 네트워크 통신 코드(Axios 등)를 수백 줄 짜야 한다.
    • OAS 파일을 Swagger Codegen 도구에 넣고 돌리면, 백엔드를 찌르는 수백 줄짜리 자바스크립트나 스위프트 **네트워크 통신 소스 코드가 1초 만에 오류 0%로 완벽하게 자동 생성(Generate)**된다. 개발자는 그 코드를 복사해다 쓰면 끝난다.

📢 섹션 요약 비유: 붕어빵을 만들 때, 팥소(백엔드 로직)가 다 끓을 때까지 밀가루 반죽 팀(프론트엔드)이 놀고 있는 것은 낭비입니다. OAS라는 완벽한 '붕어빵 쇠틀(설계 도면)'만 먼저 같이 합의해서 파놓으면, 한쪽은 팥소를 끓이고 한쪽은 가짜 팥(Mock)을 넣고 반죽 연습을 동시에 시작할 수 있어 가게 오픈 시간을 절반으로 단축하는 초효율화 공정입니다.