도메인별 API 스펙 문서화

[juwon-code]

Description

작업을 수행하는데 지침이 될 개발 문서들을 작성해야 할 필요성을 느꼈습니다.
이전 노션으로 작성한 문서가 제거된 관계로, /docs/api/에 API 스펙을, docs/sequence에 시퀀스 다이어그램을 작성합니다.

To-Do

API 문서

• 회원 API 문서 작성
• 사진 API 문서 작성

시퀀스 다이어그램

• 회원 시퀀스 다이어그램 작성
• 사진 시퀀스 다이어그램 작성

Reference

• PlantUML Language Reference Guide

[juwon-code]

Sequence Diagram을 작성하면서 정리하고 싶은 점을 기록합니다.

1. 다이어그램 파일을 무엇을 기준으로 나누면 좋을까?

API 내부 동작 방식을 순차적으로, 객체 간의 상호작용으로 표현하는 것을 목표로 하므로, 하나의 문서에 여러 API의 동작을 표현하는 것은 비효율적이란 생각이 들었습니다. 따라서, API 별로 개별 파일을 작성할 예정입니다.

2. DispatcherServlet, SecurityContextHolder 등의 Lifeline을 그려야 하는가?

개발자가 직접 호출하지 않는 프레임워크의 내부 동작을 나타내므로, 복잡도를 증가시킬 수 있습니다.
따라서 최대한 배제하며 필요한 경우에만 표현하는 것이 옳을 것입니다.
ex) GlobalExceptionHandler-직접 호출하는 것은 아니지만 예외 처리를 보여주기 위해 필요합니다.

3. 동일 클래스 내 메소드 호출의 경우 어떻게 표현해야 하는가?

동일 객체 내부 메소드의 Nested Call의 경우, 실행 과정은 필요할 경우 표현할 수 있으며, 별도의 Life Cycle로 표현할 필요는 없습니다. 다음과 같은 Self Call 방식으로 표현하면 됩니다. 단, Depth를 1로 설정하여 추가적인 Private 메소드를 호출하는 경우는 표현하지 않아야 합니다.

클래스 A에 Private 메소드 methodA, methodB가 존재하고, methodA가 methodB를 호출한다고 가정.
A --> A: Call methodA() (O)
A --> A: Call methodB() (X)

4. Setter의 경우 어떻게 표현하는가?

Setter를 예로 들 수 있는, 단순 상태 변경 메소드의 경우 Sequence Level에서 설명하지 않습니다.

5. 레이어를 어떻게 구분하면 좋을까?

다이어그램의 가독성을 올리기 위해, Participant를 특정 색상의 Box로 구분해야 합니다.

레이어 목록
Presentation Layer: 요청 매핑, 응답 반환에 사용되는 Participant가 속함. 지정 색상 없음. (ex) DispatcherServlet, Controller
Service Layer: 비즈니스 로직을 포함하고 있는 Participant가 속함. #Pink
Utility Layer: 공통 기능을 제공하는 Participant가 속함. #LightYellow
Repository Layer: DB, Redis 등과 상호작용하는 Participant가 속함. #LightGreen
Infrastructure Layer: 서비스가 동작하는 데 필요한 기반을 제공하는 Participant가 속함. #LightBlue