4강. API 계약을 문서가 아니라 스키마로 고정하기

🤔 Question

👉 API 문서는 이미 잘 작성했는데도
배포 후 다른 서비스가 깨지는 경험, 해보신 적 있나요?

Swagger 페이지도 있고
Notion 문서도 있고
PDF 스펙도 공유했는데
여전히 장애가 발생합니다.

이유는 간단합니다.
👉 문서는 읽으라고 만든 것이고, 계약은 지키라고 만드는 것이기 때문입니다.

 

🎯 문서 기반 API의 한계

문서 기반 API 개발 흐름은 보통 이렇습니다.

✔ 개발자가 먼저 API 구현
✔ Swagger 또는 위키에 문서 작성
✔ 다른 팀이 문서를 보고 연동

문제는 여기서 발생합니다.
👉 문서와 실제 코드가 쉽게 어긋난다는 점입니다.

문서는 수정되었지만 코드가 아직 반영되지 않았거나
코드는 변경되었지만 문서는 업데이트되지 않은 상태.

이 순간, 계약은 이미 깨져 있습니다.

 

🎯 계약은 사람이 아니라 시스템이 지켜야 한다

문서를 읽고 지키는 것은 사람입니다.
하지만 사람은 실수합니다.

👉 진짜 계약은 시스템이 자동으로 검증해야 합니다.

이를 가능하게 하는 것이 바로
스키마(Schema)입니다.

스키마는
"이 API는 반드시 이렇게 요청 받고
이렇게 응답해야 한다"
를 기계가 이해할 수 있는 형식으로 고정합니다.

 

🎯 OpenAPI는 문서가 아니라 계약 파일

많은 팀이 OpenAPI(Swagger)를
"문서 생성 도구"로만 사용합니다.

하지만 OpenAPI의 진짜 역할은
👉 API 계약을 코드와 분리된 스키마 파일로 고정하는 것입니다.

예시를 보겠습니다.

paths:
  /users/{id}:
    get:
      responses:
        '200':
          description: User Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string

이 스키마는
👉 "이 API는 반드시 id와 name을 반환해야 한다"
를 시스템 레벨에서 고정합니다.

이제 누군가 name 필드를 삭제하면
빌드 단계에서 바로 실패하게 만들 수 있습니다.

 

🎯 Contract-First 개발 방식

스키마를 중심에 두면
개발 순서가 완전히 바뀝니다.

1. 먼저 OpenAPI 스키마를 정의
2. 스키마로 Mock 서버 자동 생성
3. 프론트와 다른 서비스는 Mock으로 개발
4. 백엔드는 스키마를 만족하도록 구현

👉 계약이 먼저, 구현은 나중

이것이 Contract-First 개발입니다.
MSA 환경에서 가장 안전한 협업 방식입니다.

 

🎯 스키마가 바꾸는 개발 문화

스키마가 도입되면
팀의 대화 방식이 달라집니다.

❌ "이 필드 이름 바꿔도 돼요?"
⭕ "계약 스키마 변경이 필요한가요?"

❌ "일단 코드부터 짜고 문서 맞출게요."
⭕ "먼저 계약부터 합의하죠."

👉 API 논의가 코드가 아니라 계약 중심으로 이동합니다.

 

☔ 정리

👉 문서는 사람이 읽지만 계약은 시스템이 지켜야 합니다.
👉 OpenAPI 스키마는 API의 법적 계약서입니다.
👉 Contract-First 개발은 MSA 협업의 필수 전략입니다.

REST를 진짜 계약으로 만드는 순간,
API는 더 이상 깨지지 않습니다.

 

 

If I was of any help to you, please buy me coffee 😿😢😥

If you have any questions, please leave them in the comments

Buy me a coffee

▶ Youtube Sub

🧭 References

[1] reference : https://doctorson0309.tistory.com/

[2] Ads : https://apps.apple.com/us/app/beluga-classic-film-filters/id6744041061