백엔드 서버 API doc 작성과 Springdoc 자동 구성하기

관련 내용

해당 프로젝트 깃 허브

개요 목적

API doc은 서비스 기능을 사용할 수 있게 도와주는 설명서 역할을 한다.

내가 만든 영어 통문장 암기 서비스의 관리자 문장 관리 테스트 처리 API doc을 직접 표를 통해 만들어보고,

spring-doc 라이브러리의 도움을 받아 자동으로 API doc을 생성하는 방법을 알아보자.

API doc 구성 양식은 https://developers.kakao.com/docs/latest/ko/daum-search/dev-guide REST API 문서를 참고 했다.

관리자 문장 관리 & 테스트 처리 API doc

1. 관리자 문장을 추가

POST /api/admin/sentence/add

<Request>

• MessageBody

Name	Type	Description
korean	String	추가할 문장의 번역 정보
english	String	추가할 문장의 영어 정보
grammar	String	추가할 문장의 문법 정보(서버에서 제공한 문법 요소에 한함)
situation	String	추가할 문장의 상황 정보(서버에서 제공한 상황 요소에 한함)

<Response>

x

2.서버가 제공하는 문법 상황 요소 제공

GET /api/admin/sentence/selection

<Request>

x

<Reponse>

adminSentenceSuccess

Name	Type	Description
grammarList	List<String>	서버에서 제공하는 문법 요소들
situationList	List<String>	서버에서 제공하는 상황 요소들

3.서버가 제공하는 관리자 문장 목록 전부 가져오기

POST /api/admin/sentence/all

<Request>

x

<Response>

adminSentenceSuccess

Name	Type	Description
list	List<AdminSentenceDto>	관리자 문장 목록을 담은 리스트

AdminSentenceDto

Name	Type	Description
id	Long	관리자 문장 id
korean	String	관리자 문장 번역 정보
eglish	String	관리자 문장 영어 정보
grammar	Stirng	관리자 문장 문법 정보
situation	Stirng	관리자 문장 상황 정보

4.특정 관리자 문장 정보 얻기

GET /api/admin/sentence/find/{id}

<Request>

• Pathvariable

Name	Type	Description
id	Long	정보를 얻고 싶은 관리자 문장 id 입력

<Response>

adminSentenceSuccess

Name	Type	Description
adminSentenceDto	adminSentenceDto	선택한 관리자 문장 정보

AdminSentenceDto

Name	Type	Description
id	Long	관리자 문장 id
korean	String	관리자 문장 번역 정보
eglish	String	관리자 문장 영어 정보
grammar	Stirng	관리자 문장 문법 정보
situation	Stirng	관리자 문장 상황 정보

5.특정 관리자 문장 삭제하기

DELETE /api/admin/sentence/delete/{id}

<Request>

• Pathvariable

Name	Type	Description
id	Long	삭제하고 싶은 관리자 문장 id 입력

<Response>

x

6.특정 관리자 문장 수정하기

PUT /api/admin/sentence/update/{id}

<Request>

• Pathvariable

Name	Type	Description
id	Long	수정하고 싶은 관리자 문장 id 입력

• MessageBody

Name	Type	Description
korean	String	수정할 문장의 번역 정보
english	String	수정할 문장의 영어 정보
grammar	String	수정할 문장의 문법 정보(서버에서 제공한 문법 요소에 한함)
situation	String	수정할 문장의 상황 정보(서버에서 제공한 상황 요소에 한함)

<Response>

x

 

(테스트할 문장 조건 별 가져오기)

1. 테스트할 관리자 문장 조건 별 가져오기

PUT /api/admin/test/list

<Request>

• MessageBody

Name	Type	Description
userId	Long	테스트할 유저 id 정보
check	String	”NO” - 틀리거나 풀지 않은 문장 가져오기 ”WRONG” - 틀린 문장만 가져오기 ”CORRECT” - 맞춘 문장만 가져오기
grammar	String	테스트할 문법 정보
situation	String	테스트할 상황 정보

<Response>

List<AdminTestSentenceDto>

AdminTestSentenceDto

Name	Type	Description
sentenceId	Long	테스트할 문장 id
korean	String	테스트할 문장 번역 정보
english	String	테스트할 문장 영어 정보
hint	String	테스트할 문장 힌트 정보
grammar	String	테스트할 문법 정보
situation	String	테스트할 상황 정보
chekc	String	해당 문장 기존 맞음 틀림 정보

 

(테스트 결과 logstash 전달 elasticSearch 저장)

1. 관리자 문장 맞음 테스트 결과 log 처리

@POST / api/test/result/correct

<Request>

• MessageBody

Name	Type	Description
userId	Long	맞음 테스트 결과 처리할 유저 id
sentenceId	Long	맞음 테스트 결과 처리할 문장 id

<Response>

x

2. 관리자 문장 틀림 테스트 결과 log 처리

@POST / api/test/result/wrong

<Request>

• MessageBody

Name	Type	Description
userId	Long	틀림 테스트 결과 처리할 유저 id
sentenceId	Long	틀림 테스트 결과 처리할 문장 id

<Response>

x

3. 관리자 문장 힌트 봄 테스트 결과 log 처리

@POST / api/test/result/hint

<Request>

• MessageBody

Name	Type	Description
userId	Long	힌트 테스트 결과 처리할 유저 id
sentenceId	Long	힌트 테스트 결과 처리할 문장 id

<Response>

x

4. 관리자 문장 테스트 시작 시간 저장

@POST / api/test/time/start

<Request>

• MessageBody

Name	Type	Description
userId	Long	시작 시간 저장할 유저 id
sentenceId	Long	시작 시간 저장할 문장 id

<Response>

x

5. 관리자 문장 테스트 시간 정보 log 처리

@POST / api/test/time/end

<Request>

• MessageBody

Name	Type	Description
userId	Long	테스트 시간 결과 처리할 유저 id
sentenceId	Long	테스트 시간결과 처리할 문장 id

<Response>

x

멘토의 조언

Reqeust 정보를 Api doc으로 제공할 때 반드시 필요한 Required 값인지 아닌지 표시해두는 것이 좋다.

Response 정보를 API doc을 통해 제공할 때 빈 list 값을 빈 list로 제공하는 지 아니면 null 값을 제공하는 지 명시해 주어야 API doc 사용자 입장에서 빈 값 들어올 때 처리를 명확히 할 수 있다. 일반 객체 Response의 경우도 빈 값일 경우 null 인지 아니면 다른 기본 값을 제공하는 지 명시해두는 것이 좋다.

그리고 하나의 컨트롤러에는 전용 request dto와 response dto를 두는 것을 추천한다.

spring doc 라이브러리를 사용한 자동 API doc 생성

spring doc 설정 실행 방법

springdoc 라이브러리를 추가하고

//spring-doc
implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.7.0'

http://127.0.0.1:5510/swagger-ui/index.html#/ 로 접속하면 swagger가 자동으로 만들어준 api doc을 확인 할 수 있다.

API 설명 붙이기

설정할 컨트롤러에 @Opeartaion(summary 정보를 입력하여 해당 api를 설명 글을 명시할 수 있다.

//operaiton(summary 작성)
@Operation(summary = "client가 request한 alarm id를 삭제")
@PostMapping("delete/alarm")
public ResponseEntity<Void> deleteAlarm(@RequestBody UserSentenceRequest request) {
    userSentenceService.deleteAlarm(request);
    return new ResponseEntity<>(HttpStatus.OK);
}

추가 Response 지정

@ApiResponse 지정하여 추가해야 하는 response를 추가할 수 있다.

설정하는 순간 자동으로 만들어주는 response 정보는 사라진다.

@PostMapping("/signup")
@Operation(responses = {
  @ApiResponse(responseCode = "409", description = "회원 가입 email id가 중복"),
  @ApiResponse(responseCode = "200", description = "회원 가입 요청 성공")
})
public ResponseEntity<Void> signup(
  @Valid @RequestBody UserSignupRequest userSignupRequest) {
  userManageService.signup(userSignupRequest);
  emailAuthService.save(userSignupRequest.getUsername());
  kafkaEmailService.sendMessage(userSignupRequest.getUsername());
  return new ResponseEntity<>(HttpStatus.CREATED);
}