Skip to content

[스웨거] 일부 API 문서화 및 설정 변경 - #21

Merged
jongeuni merged 28 commits into
mainfrom
feature/goal-docs
May 29, 2025
Merged

jongeuni merged 28 commits into
mainfrom
feature/goal-docs

Conversation

@jongeuni

@jongeuni jongeuni commented May 27, 2025 •

Copy link
Copy Markdown
Collaborator

📌 관련 이슈

#18

✨ 작업 개요

  • 문서화 진행하였습니다
    • swagger interface와 controller 분리
    • swagger interface 이름은 우선 AControllerSwagger로 해두었습니다 (docs 패키지 안)

✅ 작업 상세 내용

  • 스웨거 문서화
    • 일부 API 제외 완료하였습니다 (목표와 투두 조회 API, 목표 수정 API 등 제외)
  • 스웨거에 token 넣을 수 있게 config 수정
  • @AuthUser @AuthToken 스웨거에서 숨겨지도록 애노테이션 수정

💬 기타 참고 사항

  • @AuthUser @AuthToken에 애노테이션 추가했는데 순서 적절한지 말씀 주세요 👍
  • resolveArgument() 리턴 타입을 UUID로 수정했는데 이렇게 해도 괜찮은지 확인 부탁드려요
  • 그리고 controller가 하나인 경우 패키지 밖으로 뺐는데 통일하는 게 좋다고 생각하시면 수정하겠습니다
  • 기획상 모티모와 1일차에 해당하는 부분을 UserController에서 가입 날짜 조회 API로 만들었습니다 의견 주세요 :-)
    • 나중에는 UserInfoController같은걸 하나 만들어도 좋을 것 같습니다
  • 필드명/코드 정렬 관련해서도 편하게 말씀해 주세요 ☺️

@jongeuni
jongeuni requested a review from qjatjr29 May 27, 2025 09:37
@jongeuni jongeuni self-assigned this May 27, 2025
@jongeuni jongeuni added the enhancement New feature or request label May 27, 2025

@qjatjr29 qjatjr29 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

고생하셨습니다~!!!! 👍

ModelAndViewContainer mavContainer,
NativeWebRequest webRequest,
WebDataBinderFactory binderFactory) throws Exception {
public UUID resolveArgument(MethodParameter parameter,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AuthTokenArgumentResolver 쪽도 수정해도 될 것 같네요
감사합니다

Comment on lines +5 to +8
public record IdRs(
String id
) {
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

여긴 모든 도메인조회시 Id를 리턴하기 위함인가요..?

  • 여기에는 어노테이션으로 스웨거 설정이 안되어 있는거 같아요

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

맞습니당 Id만 리턴하는 경우가 많아서 그경우 공통으로 쓰기 위해... 추가해뒀습니다

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • 생성 시 사용하는 Rs로 명칭 변경했습니다
    IdRs -> CreateIdRs

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Id만을 담는 공통 응답 객체를 만드는 부분에 대해 좀 고민이 되네요,, 🤔

  • 우선 어떤 도메인에서 온 ID인지 가 명확하지 않으면 응답 자체의 의미가 애매해질 것 같아요.
  • ex) 예를 들어 UserIdRs처럼 사용하는게 더 명확할 수도 있지 않을까 싶어요.

➕ CreateIdRs라는 네이밍은 "생성 시 반환하는 ID"를 의미하는 것 같은데 update나 delete 요청에서도 ID를 반환한다면 그때도 각각 UpdateIdRs, DeleteIdRs를 만들어야 하는지 의문이 들어요.

  • 응답 객체에는 어떤 값을 반환하는지에 대해 표현하는게 좀 더 중요한 것 같아요.(제 생각)
  • 위에 코멘트 남긴 것과 마찬가지로 HTTP Method로도 어떤 행동을 하는 것인지 전달될 수도 있다고 생각해요.

@jongeuni jongeuni May 29, 2025 •

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

완전 이해했습니다!.!

IdRs 자체가 편의를 위해 만든 거라 코드 품질 측면에서 봤을 땐 좋지 않게 느껴질 것 같아요

Rs모델 같은 경우 공통화 하지 않고 각 도메인에 적합한 네이밍으로 사용하는 쪽으로 변경하겠습니다 의견 감사합니다 :-)


@NotNull
@Schema(description = "목표 완료 날짜", format = "date")
LocalDate date,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
LocalDate date,
LocalDate dueDate,

여기 변수명이

  • GoalCreateRq에서는 dueDate라 통일하면 좋을거 같아요.

@Target({ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Parameter(hidden = true)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍


@Size(min = 1, max = 12)
@Schema(description = "목표 개월 수")
Integer month,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

여기서 Integer 사용한 이유는 목표 개월수가 없을수도 있어서 일까요?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

맞습니다...!


@NotNull
@Schema(description = "개월 수로 기간 설정 여부")
boolean isMonthSetting,

@qjatjr29 qjatjr29 May 27, 2025 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

이거 있어야 할까요?
저는 개월 수로 목표 설정하더라도 목표 설정 날짜 기준으로 + 개월 수 해서 완료 날짜를 설정하는거 생각했었습니다.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

date만 사용할 경우 클라이언트측에서 오늘 날짜 + 3개월 해서 날짜를 넘겨주게 되는데 그것보다 서버에서 계산하는 게 정확하다고 생각해서 우선 이런식으로 해뒀습니다 ☺️
생각했던 변수: 클라이언트에서 정확한 오늘날짜를 가지고 있지 않을 가능성이 있다고 생각 (기기 설정/캐시 문제 등)

저도 고민했던 부분이라 추가 의견 주시면 반영하겠습니다!.!

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

그렇다면!
서버가 오늘 날짜 기준으로 개월 수(month)만 받아서 완료일을 계산한다면
→ isMonthSetting 없이 month가 존재하면 plus 해주기..? 이런 식으로 사용할 수도 있지 않을까요??

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

으음... 값 null check 후 다른 동작 <- 해당 플로우가 그렇게 안정적이진 않다고 생각했습니다

month가 null일 경우 dueDate를 사용한다고 확신할 수 있는가?
-> 둘은 사실 별개의 값으로 B라는 값의 사용 여부를 A의 없음 여부로 판단할 수 없다고 생각했고, 그래서 플래그를 두는 게 맞다고 판단했어요

isMonthSetting 플래그를 사용한다면 클라이언트가 하나의 값을 정확히 의도하고 보낸 것을 신뢰할 수 있게되고, 더 명확하다고 생각했어요 (@NotNull도 사용 가능)

이런 이유로 요청 값에 대해서는 플래그를 뒀을 때 장점이 더 크다고 생각한 것 같아요 :-)...

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

좋은거 같아요!@! 🙌🏻 isMonthSetting 네이밍을 조금만 더 명확히 했으면 좋겠다는 생각은 있습니다 ..
근데 뭐가 좋으려나요..ㅎ;ㅎ;ㅎ;ㅎ;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

뭔가 딱 마음에 드는 건... 없네요

  • isMonthBased
  • isMonthMode
  • isPeriodByMonths

isMonthBased는 어떨까요? 아니면 isPeriodByMonths?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

isPeriodByMonth..?

Comment on lines +24 to +27
@PutMapping("/{id}")
public IdRs update(@PathVariable String id, GoalUpdateRq rq) {
return null;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
@PutMapping("/{id}")
public IdRs update(@PathVariable String id, GoalUpdateRq rq) {
return null;
}
@PutMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void update(@PathVariable String id, GoalUpdateRq rq) {
}

요거 IdRs 반환하는 이유 궁금해요~!

@qjatjr29

Copy link
Copy Markdown
Contributor

가입일, 닉네임 등 자주 쓰고 보안상 위험하지 않은 정보는 로그인 / 토큰 갱신시 응답에서 함께 내려주고 클라이언트가 일정 세션동안 유지하도록 하면 어떤가요..?
→ 클라이언트가 세션(앱/브라우저 메모리, 로컬스토리지 등)에 저장
→ 필요한 페이지에서 바로 사용
→ 정보 변경(닉네임, 이미지 등)이 발생하면 변경 직후 refresh

@jongeuni

jongeuni commented May 28, 2025 •

Copy link
Copy Markdown
Collaborator Author
  • ReadRs로 작성한 부분 Read 제거
  • 리턴 타입 null 말고 값 응답하도록 변경


@NotNull
@Schema(description = "개월 수로 기간 설정 여부")
boolean isMonthSetting,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

그렇다면!
서버가 오늘 날짜 기준으로 개월 수(month)만 받아서 완료일을 계산한다면
→ isMonthSetting 없이 month가 존재하면 plus 해주기..? 이런 식으로 사용할 수도 있지 않을까요??

Comment on lines +30 to +38
@Schema(description = "세부 목표 목록")
List<SubGoalCreateRq> subGoals
) {
public GoalCreateRq {
if (Objects.isNull(subGoals)) {
subGoals = new ArrayList<>();
}
}
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
@Schema(description = "세부 목표 목록")
List<SubGoalCreateRq> subGoals
) {
public GoalCreateRq {
if (Objects.isNull(subGoals)) {
subGoals = new ArrayList<>();
}
}
}
@Schema(description = "세부 목표 목록")
@JsonSetter(nulls = Nulls.AS_EMPTY)
List<SubGoalCreateRq> subGoals
) {
}

요거 subGoals가 null로 들어올 경우를 방지하기 위해 생성자에서 null 체크 후 빈 리스트로 초기화하신 부분인 것 같아요!@!
이런 경우에는 @JsonSetter(nulls = Nulls.AS_EMPTY) 어노테이션 사용할 수도 있을 거 같아요@!

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

감사합니다!.!

@qjatjr29

Copy link
Copy Markdown
Contributor

@jongeuni 👍

@jongeuni jongeuni linked an issue May 29, 2025 that may be closed by this pull request
6 of 9 tasks
@jongeuni

Copy link
Copy Markdown
Collaborator Author

가입일, 닉네임 등 자주 쓰고 보안상 위험하지 않은 정보는 로그인 / 토큰 갱신시 응답에서 함께 내려주고 클라이언트가 일정 세션동안 유지하도록 하면 어떤가요...?

좋은 것 같습니다 ☺️ 특히 가입일같이 변하지 않는 값은 토큰 갱신 시 함께 내려주고 그거 사용하면 좋을 것 같아요

@qjatjr29
말씀 주신 사항 반영 완료 했습니다!.!

}

@GetMapping
public GoalListRs readList(@AuthUser UUID userId) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
public GoalListRs readList(@AuthUser UUID userId) {
public GoalListRs getGoals(@AuthUser UUID userId) {
또는
public GoalListRs getGoalList(@AuthUser UUID userId) {

요거 readList는 어떤 것을 가져오는지 명확하지 않을 수 있을거 같아요~

➕ read는 파일이나 스트림 같은 것들을 읽을 때 사용하는 표현인거 같아서 get 을 사용하도록 하는건 어떨까요?

@jongeuni jongeuni May 29, 2025 •

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

오호 확인했습니다~
Rs같은 경우도 GoalGetRs처럼 바꾸는 게 좋을까요?

@qjatjr29 qjatjr29 May 29, 2025 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Response 같은 경우는 Get 같은건 굳이 안 넣어도 될거 같아요!

  • 어떤 값을 반환하는지만?!

여기서 GoalRs << 이라는 Rs가 있다면

public List<GoalRs> getGoalList(@AuthUser UUID userId)
public Page<GoalRs> getGoalList(@AuthUser UUID userId)

이렇게도 할 수 있을거 같긴합니다

  • 투두 리스트를 반환할 때는 Slice 사용 하는거 생각하고 있긴합니다.. (스크롤 방식이길래) - 좀 더 고민해볼예정!

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

앗 맞네요잉 헷갈렸습니다 ~! 화긴!.!

@qjatjr29

qjatjr29 commented May 29, 2025 •

Copy link
Copy Markdown
Contributor

좋은 것 같습니다 ☺️ 특히 가입일같이 변하지 않는 값은 토큰 갱신 시 함께 내려주고 그거 사용하면 좋을 것 같아요

@jongeuni
그러면 사용자 가입일 조회하는 api 삭제하는 걸까요?!

@GetMapping("/me/joined-date") // 요거

@jongeuni

jongeuni commented May 29, 2025 •

Copy link
Copy Markdown
Collaborator Author

@qjatjr29 넵 그렇게 하겠습니다 :-)
UserController와 UserControllerSwagger class는 우선 남겨둘게요 (빈 클래스로)

@qjatjr29

qjatjr29 commented May 29, 2025 •

Copy link
Copy Markdown
Contributor

특히 가입일같이 변하지 않는 값은 토큰 갱신 시 함께 내려주고 그거 사용하면 좋을 것 같아요

@jongeuni
그럼 토큰 생성 / 갱신 시에 가입일같은 변하지 않는 정보는 함께 반환하도록 수정해볼게요~!

  • 이때 createdAt 값을 이용할 것 같은데 createdAt 값을 그대로 반환하는 것
  • 현재 날짜에 맞춰서 실제 가입일 수를 계산해서 반환하는 것
  • 뭐가 더 좋은 방법일까요 ㅎ;; 의견 부탁드립니다 😭

@jongeuni

jongeuni commented May 29, 2025 •

Copy link
Copy Markdown
Collaborator Author

@qjatjr29
createdAt 값을 반환하는 게 좋을 것 같아요!

  • 이유: 사용자에 관한 기본 정보 / 가공해서 주는 것보다 정보 그대로 반환하고 사용처에서 맞게 사용하는 게 의미 있어 보임

앱으로 가면 변경이 필요할 수도 있는데 일단은 웹이니까 괜찮을 것 같습니다

+그런데... ...
약간 API가 필요하지 않을까 싶은 생각이 다시 들긴 하네요 허허

  1. 현재 '가입일'이라고는 했지만 나중에 요구사항 변경 가능성 O
    -> 이건 제 설계 이슈인듯 / 가입일이라고 하면 안됐고 목표 시작일이라는 네이밍을 썼어야 했음
  2. 토큰 응답 시 '실제 가입일 수 계산'해서 응답해주는 게 어색하게 느껴짐 <- 너무 특정 화면/기능에 특화된 코드이기 때문
  3. 2번에 더 나아가서 특정 화면/기능에 특화된 코드이기 때문에 API가 따로 필요할 것이라는 결론까지 도달 가능

의견 알려주실 수 있을까요? 😅 너무 깊게 생각한 것 같기도 하고 😅
위와 별개로 토큰 응답으로 사용자 가입일 등 메타 정보를 넘겨주는 것은 좋은 것 같아요!!

@qjatjr29

Copy link
Copy Markdown
Contributor

로그인 시 메타 정보로 함께 반환하는 방법

  • 불필요한 API 호출을 줄일 수 있을 것이라 생각합니다.
  • '가입일'은 한 번 로그인할 때 받아오면 충분하다고 생각!

메인 화면 진입 시마다 별도의 API를 호출하는 것은 낭비일 수도 있지 않을까..?

별도 API로 분리하게 된다면??
아래와 같은 경우에 좋을 것 같긴합니다.

종은님 말씀대로 가입일의 의미가 바뀔 수 있는 경우

가입일 외에도 그와 연관된 계산 로직이 필요한 경우
예: 오늘 기준으로 n일차인지에 대한 값을 반환도록 요구사항 변경시 -> 서버 연산이 필요

고려해볼 내용 🤔
그 정도는 아니겠지만,, 사용자 수가 많아질수록 자주 호출되는 API는 성능에 문제가 생길 수도 있을 것 같아요!!

  • 뭐 이때 쯤이면 캐싱(Redis ,, 등)을 도입하는 방법도 고려해볼 만 한 것 같습니다.

해당 가입일 정보가 변화 가능성 있는지??? 를 고려해서 다시 생각해 볼 필요가 있을 것 같아요.. 어렵네요

또, createdAt... 이거 서버에서 계산된 결과를 보여주는게 더 일관성있고 안전할거 같긴한데 흐음 그렇네요,, 특정 화면에만 사용하는 기능이라 아아아아ㅏ아아아ㅏㅏㅏ
좀 더 고민해보겠습니다 😢

(질문)
목표 시작일 << 얘를 이해를 못해서 저희 목표 시작일도 보여주는게 있나요?

@jongeuni

Copy link
Copy Markdown
Collaborator Author

@qjatjr29
ㅋㅋㅋㅋ 화긴...!
이렇게 정리하겠습니다

  • 가입일 API: 우선 사용하지 않음
  • 토큰 응답 시 createdAt 계산: 좀 더 고민해보기

목표 시작일의 경우 어제 나눈 대화랑 헷갈렸던 것 같아요 (...)
어제 PM님이 '목표 시작한 날짜'로 보여주자고 하셨어서... <- 제가 앗 가입일로 보여주면 좋지 않으까요라고 함
-> '함께한지 n일째'라고 되어있는데 '함께한지'에 대한 정의가 바뀔 수 있다고 생각했던 것 같아요 그래서 '가입 날짜 응답'으로 API를 만들었던 게 미스였다고 생각했음!!

어쨌뜬~ 토큰 응답값으로 사용하는걸로 가시죵 good입니다

@jongeuni
jongeuni merged commit ae54775 into main May 29, 2025
@jongeuni jongeuni mentioned this pull request Jun 16, 2025
3 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[docs] API별 스웨거 작성

2 participants