OpenAPI 와 스웨거를 활용한 실전 API 설계 (feat. 요구사항으로 부터 도메인 모델링하기)

Designing APIs with Swagger and OpenAPI(OpenAPI 와 스웨거를 활용한 실전 API 설계) - 조시 포널랫, 루카스 로젠스톡 의 책을 읽고 특정 부분을 정리한 글입니다.

 

OpenAPI를 더 유연하게 사용할 수 있는 방법을 기대한 책이었지만, 프로젝트를 전반적으로 진행하며 클라이언트와 서버간의 협업과정에서의 도메인 모델을 상세하게 구축해나가는 부분이 인상깊어 책의 전체 내용이 아닌 해당 부분에 대해서만 정리하고자 합니다.

 

📌 체크포인트

1. 해당 책에서는 [펫시터 구인구직 서비스] 라는 가상의 서비스를 주제로 설계해 나갑니다.

---

[목차]

1. 도메인 모델링과 API
   1. API 에 사용할 도메인 모델링
2. 도메인 모델 추출하기
   1. 모델에 사용되는 개념 추출하기 - 펫시터 도메인 모델
   2. 도메인 모델에 속성 추출하기
   3. 사용자 스토리 작성하기
   4. 사용자 스토리와 도메인 모델 매핑하기
   5. 사용자 스토리에서 새로운 도메인 모델 추출하기

 

---

1. 도메인 모델링과 API

✔️ 도메인 모델링 : 풀어야할 문제가 있는 도메인(관심영역)을 컴퓨터 소프트웨어로 구현할 수 있도록 기술하는 과정

• 모델은, 반려견 모델처럼 하나의 개념에 대한 표현을 의미할 때도 있으며
• 도메인 모델처럼 반려견 모델을 포함한 영역 전체를 의미하기도 합니다.

 

API 에 사용할 도메인 모델링

• 비지니스로직에 밀접한 관계를 가지는 클래스나 관계형 데이터베이스 테이블은 대부분 내부 처리 과정에 적합한 상세 구현에 가깝습니다.
• 하지만, API 는 애플리케이션의 뷰(View)계층에 더 가깝습니다. API는 시스템을 명확하게 구분하는 경계이고, 잠재적으로 내부 복잡성을 숨기는 추상 계층 역할을 수행하기도 합니다.
• API 설계자는 서버가 아닌 클라이언트 관점에서 API를 바라보아야 합니다.

 

---

 

2. 도메인 모델 추출하기

(1) 모델에 사용되는 개념 추출하기 - 펫시터 도메인 모델

✔️모델 생성을 위해서는 첫번째로 도메인 모델에 포함될 것 같은 모든 개념을 나열하는 것입니다.

• 반려동물 주인과 돌봄 도우미가 애플리케이션을 사용하므로 사용자(User) 라는 모델이 필요합니다.
• 반려동물 주인은 구인 공고를 등록하고, 돌봄 도우미는 구인 공고를 보고 지원하므로 구인 공고(Job)이라는 모델이 필요합니다.
• 구인 공고는 개를 다루는 내용이므로 반려견(Dog) 모델이 필요합니다.

---

(2) 도메인 모델에 속성 추출하기

User - (id, email, password, name, role)

• 사용자는 반려동물 주인으로써의 사용자, 반려동물 돌봄 도우미로써의 사용자, 관리자로써의 사용자 등과 같은 여러 역할을 가질 수 있습니다. (Role)
• 그 외의 사용자에게 필요한 속성으로 "이메일 주소, 비밀번호, 이름" 등의 공통적인 속성을 예상할 수 있습니다.
• 백엔드 개발자로써, 도메인을 바라보았을 때 "변경되지 않을 식별자가 필요합니다." 이메일, 주소, 이름은 변경될 가능성이 있으므로 ID 속성을 추가합니다.

 

Job 과 Dog

→ User는 흔한 도메인이라 비교적 쉽게 속성을 유추할 수 있었지만, 펫시터 서비스만의 도메인인 구인공고(Job)과 반려견(Dog)은 서비스에 필요한 속성을 도출해 내야합니다. (현실과 다른 소프트웨어세계 안에서의 도메인)

→ 책에서는 브레인 스토밍을 이용해 사용자 입장에서 모델을 바라보도록하여 공통 질문을 추출합니다. 
("당신에게 내 개를 돌봐달라고 요청했는데, 당신은 내 개를 처음보는 상황이라면 무엇을 알고 싶을까요?" → 서비스의 핵심 비지니스)

1. 돌봄은 언제 시작해서 얼마 동안 해야 되는가?
2. 돌봄에는 어떤 일이 포함되는가? 산책, 집 안에서 돌보기, 또는 집 밖에서도 돌봐야 하는가?
3. 반려견 이름과 품종 등 기본 정보

→ 속성 추출

Job (구인 공고)	Dog (반려견)
시작 시간 종료 시간 활동	이름 나이 품종 크기

도메인 모델에 속성 추출

---

(3) 사용자 스토리 작성하기 

• 도메인 모델을 완성하고 애플리케이션을 개발하려면 모델과 모델이 취할 수 있는 행위, 또는 모델에 가해지는 행위 사이의 연결에 대해 논의할 필요가 있습니다.
• 사용자 스토리를 이용하여 애플리케이션 기능을 기술하는데 사용할 수 있습니다.

 

✔️ 사용자 스토리란?

• 사용자 스토리는 소프트웨어 제품의 사용자 관점에서 작성하며, 소프트웨어 안에서 무언가를 달성하기 위해 해야하는 활동을 기술하는 → 요구사항을 분석하는 데 사용하는 비형식적인 프로젝트 관리 방법

✔️ 사용자 스토리 템플릿

• 나는 <역할> 로서 <기능>을 할 수 있고, 그 결과 <보상>을 받는다. ("그 결과 ~ 보상은" 필수는 아닙니다.)
• <사전 조건>이 주어지면 나는 <기능>을 할 수 있다.
• ex)
  • 반려동물 주인으로서 나는 구인 공고를 올릴 수 있고, 그 결과 휴일에 자유로운 시간을 보 낼 수 있다.
  • 구인 공고가 올려졌으므로 구인 공고 상태를 확인할 수 있다.

↓

가. 반려동물 주인(사용자 스토리)

1. 나는 역할을 선택해서 새 사용자를 등록할 수 있고, 그 결과 로그인할 수 있다.
2. 나는 로그인할 수 있고, 그 결과 마켓플레이스를 이용할 수 있다.
3. 나는 펫시터에 내 반려견에 대한 설명을 포함하는 구인 공고를 올릴 수 있고, 그 결과 반려동물 돌봄 도우미가 구인 공고를 보고 지원할 수 있다.
4. 나는 내가 등록한 구인 공고 목록을 확인할 수 있다.
5. 구인 공고를 등록하면 상세 내용을 조회하고 수정할 수 있다.
6. 구인 공고를 등록하면 등록한 구인 공고를 삭제할 수 있다.
7. 구인 공고를 등록하면 구인 공고에 지원한 돌봄 도우미를 확인할 수 있다.
8. 적절한 지원자가 있다면 승인할 수 있다.
9. 나는 내 계정 정보를 수정할 수 있다.
10. 나는 내 계정을 삭제할 수 있다.
    
    

나. 돌봄 도우미 (사용자 스토리)

1. 나는 역할을 선택해서 새 사용자를 등록할 수 있고, 그 결과 로그인할 수 있다.
2. 나는 로그인을 할 수 있고, 그 결과 마켓플레이스를(펫시터 서비스) 사용할 수 있다.
3. 나는 돌봄이 필요한 반려동물 목록을 조회할 수 있다.
4. 마음에 드는 구인 공고가 있으면 지원할 수 있다.
5. 나는 내 계정 상세 정보를 수정할 수 있다.
6. 나는 내 계정을 삭제할 수 있다.
   
   

다. 관리자 (사용자 스토리)

1. 나는 로그인을 할 수 있고, 그 결과 어드민 기능을 사용할 수 있다.
2. 나는 내 계정 상세 정보를 수정할 수 있다.
3. 나는 다른 사용자의 계정 상세 정보를 수정할 수 있다.
4. 나는 다른 사용자가 등록한 구인 공고를 수정할 수 있다.
5. 나는 내 계정을 삭제할 수 있다.

---

(4) 사용자 스토리와 도메인 모델 매핑하기

✔️ 이제 위에서 추출한 유저, 구인 공고, 반려견 - 3개의 모델과 추출된 사용자 스토리의 행위와 관계를 매핑해봅니다.
✔️ 먼저 여러 모델에 걸쳐 동일하거나 비슷한 내용을 담고 있는 사용자 스토리를 점검합니다.

사용자 

나는 역할을 선택해서 새 사용자를 등록할 수 있다.

• 반려동물 주인, 돌봄 도우미에게 공통적으로 해당 됩니다.
• 사용자는 역할과 무관하게 사용자 등록을 해야합니다.
• 따라서 사용자 모델에 필요한 Register(사용자 등록) 행위를 도출할 수 있습니다.
  
  

나는 내 계정으로 로그인할 수 있다.

• 세 역할의 사용자 스토리에 모두 포함되며 역할에 무관한 사용자 스토리 입니다.
• 따라서 사용자 모델에 Login(로그인) 행위를 추가합니다.
  
  

나는 내 계정을 삭제할 수 있다, 나는 내 계정을 삭제할 수 있다.

• 모든 사용자 스토리에 포함되므로 Modify(수정) 행위를 추가합니다.
• 또한, 상세정보를 수정하기위해서는 조회를 해야하므로 View(조회) 행위도 추가합니다.
• 마찬가지로 Delete(삭제) 행위를 추가해줍니다.

---

반려동물 주인 (구인 공고)

나는 펫시터에 내 반려견에 대한 설명을 포함하는 구인 공고를 올릴 수 있다.

• 구인 공고 모델의 생성과, 반려견 모델 관련 내용이 함께 포함된 사용자 스토리 🤨
• 사용자 스토리에 따르면, "반려견 정보를 포함하는 구인 공고를 게시하는 일" 은 하나의 단계로 처리됩니다.
• 반려견 정보를 등록, 수정, 삭제, 조회하는 사용자 스토리는 아직 존재하지 않습니다.
  • 팀은 최대한 단순하게 관계를 유지하길 원하기에 새로운 사용자 스토리를 만들지 않는다고 가정합니다.
• 구인 공고는 오직 한 마리의 반려견에 대한 정보만 포함하고, 모든 반려견은 오직 하나의 구인 공고에만 포하모디므로 둘은 일대일 매핑 관계입니다. (현실과는 다른 소프트웨어 상에서, 단순화를 위해 1:1 매핑으로 가정)
• 위에서 도출된 약속(요구사항)을 기반으로 → 반려견 설명이 구인 공고에 포함되므로, 실제로는 동일한 반려견에 대한 정보라고 할지라도 서로 다른 구인 공고에 포함된 반려견 정보는 다른 반려견 정보로 인식됩니다.

나는 내가 등록한 구인 공고 목록을 확인할 수 있다.

• 반려동물 주인이 등록한 구인 공고 목록을 조회할 수 있어야 하므로 구인 공고 모델에 List my own(내 공고 목록 조회) 행위를 추가합니다.
• 이를 위해서, 구인공고를 생성한 반려동물 주인이 어떤 사용자인지 알아야 합니다. (User 와 Job의 관계)
  
  

---

(5) 사용자 스토리에서 새로운 도메인 모델 추출하기

구인 공고를 등록하면 상세 내용을 조회, 수정, 삭제, 지원한 돌봄 도우미를 확인할 수 있다.

• 조회, 수정, 삭제 행위를 추가해 줍니다.
• 지원한 돌봄 도우미 사용자를 반려동물 주인이 확인해야하므로 사용자는 구인공고에 지원하다라는 관계를 가집니다.
• 👏 하지만, '지원 목록 조회' 에 대한 행위는 Job 과 User 둘 모두에게 관련이 있을 수도 있습니다.
• 👏 또한 '지원' 이라는 새로운 행위가 등장했고, 이 행위에 새로운 이름을 붙여야 한다면 도메인 모델에 새로운 개념을 도입할 필요가 있는 징조라고 볼 수도 있습니다.
• → 책에서는, "구인공고 지원" 이라는 모델을 새롭게 생성하여 두 도메인 모델과 연결합니다. 

새로운 도메인 모델 추출

---

구인공고 지원

적절한 지원자가 있다면 승인할 수 있다.

• 구인공고 지원에 대하여 승인하다(Approve)라는 행위를 추가해줍니다.
• 처음에 존재하지 않았던 구인공고 지원 모델이 생겼고, 행위에 대한 결과를 알 수 있어야 하므로 상태 속성과 ID 속성을 추가해줍니다.
  
  

나는 마음에 드는 구인 공고가 있으면 지원할 수 있다.

• 구인공고 지원이 하나의 모델이 되었으므로, 사용자가 구인공고지원을 했을때, 구인공고 지원이 생성되어야합니다. (Create)

---

이후 책에서는 변경되는 요구사항에 맞춰, 반려견 → 반려동물로 변경하기, 그에따른 사용자 스토리 검토, 서브타이핑(다형성)으로 도메인 모델 구축하기 등의 과정이 이루어지지만, 생략하겠습니다 ㅎ

 

그럼 끝!