HTTP API를 추가한다.

[woowahan-pjs]

Vaadin View로만 호출할 수 있는 Service 기능이 있다. Controller를 추가하여 HTTP 통신으로도 호출할 수 있게 한다.
Spring REST Docs, Spring HATEOAS 등의 도입도 고려해 본다.

관련 이슈: #223

[NewWisdom]

• 07/10 수정

EvaluationTargetController

• Mockk로 컨트롤러 테스트 구현
• Spring Rest Docs를 사용해 문서화를 진행했지만 요청, 응답 필드에 대한 Description 검토 필요

EvaluationTargetService

평가 대상자(evaluation target): 이전 평가에서 합격한 지원자. 이전 평가가 없는 경우 모집에 대한 전체 지원자다.

• EvaluationTargetService 의 getById(), findAllByEvaluationId() 는 같은 서비스 내에서만 호출되기 때문에 (일단) 매핑되는 Controller를 만들지 않음

[GET] "/api/recruitments/{recruitmentId}/evaluations/{evaluationId}/targets/{keyword}"

• findAllByEvaluationIdAndKeyword()
• 평가 id와 키워드(이름, 이메일)로 평가 대상자를 조회한다

[PUT] "/api/recruitments/{recruitmentId}/evaluations/{evaluationId}/targets/renew"

• load()
• 이전 평가와 평가 대상자 존재 여부를 통해 저장하거나 갱신한다 (EvaluationTargetService의 ****load 테스트 참고)
  • 이전 평가가 없고 저장 된 평가 대상자가 없을 경우 저장하고 불러온다
  • 이전 평가가 있고 저장 된 평가 대상자가 없을 경우 저장하고 불러온다
  • 이전 평가가 없고 저장 된 평가 대상자가 있을 경우 갱신하여 불러온다, 새로 등록된 지원자를 평가 대상자에 추가한다
  • 이전 평가가 있고 저장 된 평가 대상자가 있을 경우 갱신하고 불러온다, 이전 평가의 평가 대상자의 평가가 FAIL로 바뀌면 제거한다
  • 현재 평가를 불러올 때, 평가 대상자가 부정행위자로 지정되어 제거될 경우 현재 평가에만 영향이 가는지 확인한다

[GET] "/api/recruitments/{recruitmentId}/evaluations/{evaluationId}/targets/{targetId}/grade"

• getGradeEvaluation()
• 평가 대상 id로 채점 정보를 불러온다

[PATCH] "/api/recruitments/{recruitmentId}/evaluations/{evaluationId}/targets/{targetId}/grade"

• grade()
• 평가 완료 후 점수를 매긴다
  • 평가 대상 지원자를 평가하면 평가 상태, 특이사항, 평가 항목에 대한 점수들이 변경된다
• 추후 다시 논의

RecruitmentRestController

• 기존에 있던 메서드를 포함하여 Mockk로 컨트롤러 테스트 구현
• findAllRecruitments(), deleteById(), getById(), getNotEndedDataBㅅ함yId() 는 아직 문서화를 진행하지 못함
• 나머지 메서드는 Spring Rest Docs를 사용해 문서화를 진행했지만 요청, 응답 필드에 대한 Description 검토 필요

recruitmentService

모집(recruitment): 우아한테크코스 과정에 참여할 사람을 널리 알려 뽑아 모음.

recruitmentItemService

모집 항목(recruitment item): e.g. 프로그래밍 학습 과정과 현재 자신이 생각하는 역량은? (1000자 이내)

[GET] "/api/recruitments" - 기존 API

• findAllNotHidden()
• 공개된 지원서 목록을 가져온다
  • recruitmentService#findAll() [모든 지원을 가져온다] 와 반환되는 DTO가 다른데, 이를 관리자 권한에 따라 나눌지 논의

[GET] "/api/recruitments/{id}/items" - 기존 API

• findItemsById()
• 지원 id로 지원 항목들을 가져온다

[POST] "/api/recruitments"

• save()
• 지원과 지원 항목을 저장한다

[DELETE]"/api/recruitments/{id}"

• deleteById()
• 모집 id로 모집을 삭제한다
  • 테스트 문서화는 아직

[GET] "/api/recruitments/{id}"

• getById()
• 모집 id로 모집을 가져온다
• 테스트 문서화는 아직
  • recruitmentService#getNotEndedDataById() [모집 id로 종료되지 않은 모집 데이터를 가져온다] 와 반환되는 DTO가 다른데, 이를 관리자 권한에 따라 나눌지 논의

[논의 사항] 관리자 권한에 따라 DTO를 나눌 API와 서비스 메서드

[GET] "/api/recruitments"

• recruitmentService#findAllNotHidden()
  • 공개된 지원서 목록을 가져온다
  • Return : List<RecruitmentResponse>>
• recruitmentService#findAll()
  • 모든 지원을 가져온다
  • Return : List<Recruitment>>

[GET] "/api/recruitments/{id}"

• recruitmentService#getNotEndedDataById()
  • 모집 id로 모집을 가져온다
  • Return : Recruitment
• recruitmentService#getNotEndedDataById()
  • 모집 id로 종료되지 않은 모집 데이터를 가져온다
  • Return : RecruitmentData

[Rok93]

진행 사항

• 해당 컨트롤러들(EvaluationRestController, ExcelRestController)은 문서화 진행 X
• Mockk 라이브러리를 적용하여 테스트 코드 작성

EvaluationRestController

(1) - [POST] "/api/recruitments/{recruitmentId}/evaluations"

• EvaluationService#save()
• 평가를 생성(= 추가)하는 기능

(2) - [GET] "/api/recruitments/{recruitmentId}/evaluations/{evaluationId}"

• EvaluationService#getDataById()
• 한 개의 평가를 조회하는 기능

(3) - [GET] "/api/recruitments/{recruitmentId}/evaluations"

• EvaluationService#findAllWithRecruitment()
• 모든 평가를 조회하는 기능 (모집 관계X)

(5) - [DELETE] "/api/recruitments/{recruitmentId}/evaluations/{evaluationId}"

• EvaluationService#deleteById()
• 특정 평가를 삭제하는 기능

ExcelRestController

(6) - [GET] "/api/recruitments/{recruitmentId}/applicants/excel"

• ExcelService#createApplicantExcel()
• 특정 모집에 지원한 모든 참가자들의 정보를 엑셀 파일로 추출하는 기능

(7) - [GET] "/api/recruitments/{recruitmentId}/evaluations/{evaluationId}/targets/excel"

• ExcelService#createTargetExcel
• 특정 평가의 평가대상(=evaluationTarget ?)들을 엑셀 파일로 추출하는 기능

[knae11]

• API 설계하면서 나온 내용들을 정리하였습니다.

API 설계

• 용어사전 이슈 참고링크
• /api 로 시작

모집

• /api/recruiments

평가

• /api/recruiments/{recruimentId}/evaluations
• 설명
  • 그 모집의 1,2,3차 평가 내용
  • 2기 모집의 평가내용, 3기 모집의 평가내용 등 recruitmentId로 구분
  • 모집에 종속적

지원자

• /api/applicants
• 설명
  • 지원자에 바로 접속 가능(모집이나 평가에 종속적이지 않음)
  • v2.0에서 개발할 user의 개념과 같다고 생각하면 된다.
  • 개인 정보등이 포함 될 예정이며, /api/users 로 변경될 가능성 있음
  • 그 지원자! 3기도 쓰고 4기도 쓴 그 지원자!

평가 대상자

• /api/recruiments/{recruimentId}/evaluations/{evaluationId}/targets
• 설명
  • 3기 모집의 1차 평가의 평가대상자들!
  • 그 모집의 2차 평가 대상들은 1차 평가 대상자들과 다를 것이므로 evaluationId 로 구분됨

지원서

• /api/recruiments/{recruimentId}/application-forms
• 설명
  • 그 모집의 지원서 리스트
  • 평가 대상자 혹은 지원자를 path에 넣지 않은 이유는 블라인드 등의 고려사항이 있을 수 있으므로 지원자 자체에 종속되선 안 될 것으로 판단
  • application-forms에 대한 용어는 논의가 필요

부정행위자

• /api/cheaters
• 설명
  • 영원한 블랙리스트에 오름
  • global
  • 어떤 모집, 어떤 평가였는지 상관 없음

[woowahan-pjs]

아래 원칙을 따르되 이해관계자가 최대한 이해할 수 있는 방식으로 API를 설계한다.

• 모든 경로는 kebab-case로 작성한다. (e.g. /api/application-forms)
• 엔티티를 나타내는 구문은 복수형으로 작성한다. (e.g. /api/recruiments)
• 경로 변수는 식별자만 허용한다. (e.g. /api/recruiments/1)
  • 조회 조건을 경로 변수에 넣으면 특수 문자가 들어왔을 때 오작동하기 쉽다.
  • 같은 자료형의 조회 조건을 2개 이상 만들 때 혼란이 발생한다.
• 요청 메서드로는 잘 설명되지 않거나 명시적으로 수행하려는 경우 동사를 뒤에 붙인다. (e.g. /api/recruitments/{recruitmentId}/evaluations/{evaluationId}/targets/renew)
• 부모-자식 관계가 헷갈릴 때 부모 없이 자식을 지칭하는 것이 가능한지 생각해 본다.
  • 부모를 통해 자식을 지칭하거나, 부모 없이 자식을 지칭할 수 있다면 두 가지 방법을 모두 설계할 수 있다.