UML과 Swagger를 연결해 API 명세 일관성 관리하기

API는 시스템 사이의 약속이다. 도메인 모델은 따로 관리되고 OpenAPI 문서는 구현 뒤에 따라붙는 구조라면, 계약은 쉽게 어긋난다. UML 모델과 OpenAPI(Swagger) 명세를 연결하면 요구사항, 설계, 구현, 문서를 하나의 흐름으로 관리할 수 있다.

UML은 시스템의 구조와 행위를 표현하는 표준 모델링 언어다. 클래스·컴포넌트·시퀀스 다이어그램으로 도메인과 책임, 상호작용을 드러낸다. API 설계는 리소스 경계, 엔드포인트, 페이로드 스키마, 상태 코드, 보안 정책을 외부 계약으로 구체화하는 작업이다.

Swagger는 OpenAPI 명세를 둘러싼 생태계와 도구 집합이며, OpenAPI는 HTTP API를 YAML 또는 JSON으로 기술하는 표준 포맷이다. Swagger UI·Editor와 OpenAPI Generator를 사용하면 문서, Mock, Stub 코드, SDK 생성까지 자동화할 수 있다.

모델과 API 계약을 같은 흐름으로 관리하기

모델 주도 접근에서는 UML을 단일 진실 소스로 두고 OpenAPI를 생성한다. 반대로 API-first로 만든 OpenAPI를 UML에 역투영해 설계 맥락과 추적성을 유지할 수도 있다.

일반적인 매핑은 다음과 같다. UML 클래스는 OpenAPI Schema가 되고, 연관과 컴포지션은 $ref 또는 중첩 스키마로 표현된다. 오퍼레이션은 paths와 HTTP 메서드로 옮겨가며, 시퀀스 다이어그램은 예제·상태 전이·오류 흐름 문서에 반영된다.

이 연결이 유지되면 요구사항에서 UML 요소, OpenAPI 경로와 스키마, 테스트 케이스까지 양방향 추적이 가능해진다. 변경 이력과 영향 범위를 분석하기 쉬워지고, 명명 규칙·스테레오타입·태그도 생성 규칙의 일부로 관리할 수 있다.

타입 매핑에서는 UML primitive를 OpenAPI type·format에 연결한다. 0..1, 1..*, pattern, length 같은 제약은 JSON Schema 제약으로 변환한다. 스키마 린팅, 브레이킹 체인지 검출, 용어 사전 일치성 검사를 자동화하면 모델과 명세 사이의 편차를 조기에 찾을 수 있다.

모델링에는 PlantUML, Visual Paradigm, Enterprise Architect 등을 사용할 수 있다. 명세와 코드 생성에는 OpenAPI Generator, Swagger UI·Editor가 쓰이며, Prism·Mockoon은 모킹에, WireMock·Dredd는 계약 테스트에 활용할 수 있다. CI에서는 모델 변환부터 명세 생성, 코드 생성, 테스트, 배포까지를 하나의 파이프라인으로 구성한다.

변환 과정에서 검증해야 할 지점

⤢✕

변환 전에는 타입 매핑 테이블과 패키지-네임스페이스 규칙을 적용하고 모델 제약을 검사한다. 순환 참조가 발견되면 allOf·oneOf 분해 또는 $ref 리팩터링이 필요하다. 1..1인데 nullable로 표현된 다중성 불일치처럼 모델 제약에 맞지 않는 경우에는 생성을 중단하고 모델 수정을 요구한다. 예약어 충돌에는 정해 둔 네이밍 스키마의 자동 치환 규칙을 적용한다.

변환 결과에는 openapi.yaml, Swagger UI 문서, Stub 또는 SDK 코드가 포함될 수 있다. 후처리 단계에서는 린트와 정렬을 수행하고 예제 및 샘플 페이로드를 채운다.

서비스 상황에 따른 적용 방식

신규 서비스에서는 UML 클래스·시퀀스 다이어그램으로 도메인을 잡은 뒤 «resource», «dto», «error» 스테레오타입을 지정할 수 있다. 변환 도구로 OpenAPI를 생성하고 Swagger UI에서 검토한 다음, Mock을 이용해 프런트엔드 개발을 병행한다. 오류와 페이징처럼 반복되는 스키마는 재사용 패키지로 관리하고 권한 스코프도 표준화한다.

레거시 API는 기존 OpenAPI나 코드에서 UML 리버스 모델을 생성하는 방식으로 시작한다. 용어와 중복 스키마를 정리한 뒤 표준화된 명세를 다시 생성한다. 이 과정에서는 V1·V2 호환성 레이어를 유지하고 브레이킹 변경을 최소화하며 Deprecation 헤더를 도입하는 방식이 유효하다.

마이크로서비스 환경에서는 공유 커널에 해당하는 공통 스키마를 Git 서브모듈로 두고 서비스별 명세에서 $ref로 참조할 수 있다. 계약 테스트로 서비스 간 의존성 파손을 막고, 검증을 통과한 경우에만 배포하도록 스키마 릴리스 게이트를 적용한다.

OpenAPI 명세와 코드 생성 예시

이 예시는 Java 17 또는 Node 18, Python 3.11 이상 환경과 openapi-generator-cli 7.x, Swagger UI 5.x, PlantUML 1.2023.x 또는 상용 UML 도구를 전제로 한다.

Order(id: UUID, total: Money) UML 클래스는 components.schemas.Order로, OrderService.create(Order) 서비스 오퍼레이션은 POST /orders로 매핑할 수 있다.

openapi: 3.0.3
info:
  title: Order API
  version: 1.0.0
paths:
  /orders:
    post:
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Order"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "400":
          description: Validation error
components:
  schemas:
    Order:
      type: object
      required: [id, total]
      properties:
        id:
          type: string
          format: uuid
        total:
          type: number
          format: double

# OpenAPI Generator 설치(1회)
npm install -g @openapitools/openapi-generator-cli@^2

# FastAPI 서버 스텁 생성
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python-fastapi \
  -o ./server-stub

# TypeScript Axios SDK 생성
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./sdk

생성된 server-stub 디렉터리에서는 uvicorn app.main:app --reload을 실행한다. http://localhost:8000/docs에서 Swagger UI와 엔드포인트를 확인하고, CI에서는 spectral lint와 openapi-diff로 브레이킹 변경을 검출한다.

스키마·행위·보안에 적용하는 매핑 규칙

구조를 옮길 때 클래스는 Schema가 되고, 카디널리티·패턴·범위 같은 필드 제약은 JSON Schema 제약으로 전달된다. 상속은 allOf, 합성은 내포 또는 별도 스키마 $ref, 연관은 $ref 참조로 표현한다.

행위 관점에서는 오퍼레이션을 HTTP 메서드와 경로로 변환하고, 입력·출력 DTO를 requestBody와 responses에 배치한다. 시퀀스 다이어그램의 흐름은 예제 시나리오, 상태 코드, 헤더, 리트라이 정책 문서로 연결된다.

보안 모델도 명세에 포함한다. «secured(scope:orders.write)»는 OAuth2 스코프로, «idempotent»는 Idempotency-Key 헤더 설계로 매핑할 수 있다. OAuth2/OIDC 스키마와 최소권한 스코프를 명세화하고 민감정보 마스킹 예제를 제공한다. 오류는 code, message, details를 갖는 표준 스키마로 통일하며, 추적을 위한 correlation-id 헤더를 정의한다. URI 또는 Header 기반 버전 전략을 일관되게 적용하고 Deprecation 정책과 타임라인도 명시한다.

설계 출발점별 차이

접근 방식	성능	확장성	일관성	안정성	운영 편의
UML-first	중간 (명세 계층 추가 오버헤드 경미)	높음 (도메인 재사용 용이)	높음 (단일 모델 소스)	높음 (변경 영향 분석 용이)	중간 (도구 학습 필요)
API-first	중간	높음 (계약 중심 협업)	중간 (모델 부재 시 편차)	중간	높음 (도구 생태계 성숙)
Code-first	높음 (최소 중간 산출물)	중간 (팀/언어 종속)	낮음 (문서/코드 불일치 위험)	중간 (리팩터링 리스크)	높음 (개발자 친화)

UML-first는 초기 모델링 비용이 늘어나는 대신 장기 유지보수 비용 절감을 기대할 수 있다. Code-first는 빠르게 시작할 수 있지만 문서와 모델의 일관성이 낮아질 위험이 있다. API-first는 계약이 명확하다는 장점이 있지만 도메인 모델이 부실하면 공통 스키마가 난립할 수 있다.

계약 테스트와 자동 검증을 도입하면 스키마 불일치·계약 파손 결함률은 20~~40% 감소한다. 자동 문서, 샘플, SDK 제공은 온보딩 시간을 30% 단축하며, Stub·SDK 반복 개발의 자동화는 릴리스 리드타임을 15~~25% 줄인다. 도메인 언어를 정립하고 팀 간 의사소통 품질을 높이는 효과도 있다. 변경 영향이 보이기 때문에 릴리스 예측 가능성이 높아지고, 설계 산출물은 감사와 컴플라이언스 대응에도 활용하기 쉬워진다.

신규 서비스에는 UML-first와 API-first 혼합 전략을 적용할 수 있다. 레거시 환경에서는 역공학과 계약 테스트를 함께 도입해 모델, 명세, 구현 사이의 변경 리스크를 관리한다.