[Wee.T] 커뮤니티 REST API 개발, Swagger를 이용한 문서 자동화 설정

 

 

 

 

Wee.T의 커뮤니티는 REST API 방식으로 개발하고, API 문서는 Swagger를 적용하여 자동화 하였습니다.

 

REST API 설계시 고려했던 점

1. URI 규약을 준수하여 보다 Restful하게 만들기
2. 용도에 맞는 HTTP Method를 사용할 것(GET, POST, PUT, DELETE)

Swagger를 사용한 이유?

1. API문서의 자동화가 가능하고, 내 마음대로 커스터마이징 할 수 있다는 장점이 있습니다.
2. swagger-ui 내에서 테스트가 가능하다는 점. 어떤 형식으로 리턴되는지 바로바로 확인할 수 있다는 장점
3. (주관적) 다른 API 문서 툴과 비교하여 가장 직관적이라고 생각되는 UI

 

* 스웨거의 초기 세팅 과정은 이전 포스팅에 작성하였습니다.

https://shurimp.tistory.com/72

[Spring] Swagger 2.x.x 버전 적용하는 방법

 

 

---

 

URI Mapping

 

일반적으로 통용되고 있는 URI 매핑 규칙에 따르도록 노력했습니다.

 

1. 소문자를 사용한다. 

- 카멜방식이 아닌 소문자를 사용합니다. 자바의 네이밍 규칙은 카멜기법이라 처음에 매핑 설계를 할 때엔 대문자로 작성하기도 했는데, 소문자로 수정하였습니다.

 

2. 언더바 대신 하이픈을 사용한다.

- 두 단어 이상 길어질 경우 하이픈을 사용합니다. 제가 개발한 API는 애초에 긴 단어를 사용하지 않고 명확한 한 단어로 표현하려고 해서 이 규칙은 적용하지 않았습니다.

 

3. 마지막에 슬래시를 포함하지 않는다.

 

4. delete, update 등 uri에 행위를 나타내는 단어를 포함하지 않는다.

- 행위는 HTTP Method를 사용하여 나타냅니다. 따라서 CRUD의 경우, 동일한 URI에 HTTP Method를 다르게 매핑하였습니다.

 

5. 동사보다는 명사를 사용하여 나타낸다. 그러나 컨트롤 자원을 의미하는 경우 예외적으로 동사를 허용한다.

- 게시글은 board, 목록은 list와 같이 명사를 사용하였습니다. 동사를 사용한 경우는 아래와 같이 게시글 추천API에 적용하였습니다. (vote)

 

 

6. 슬래시(/)는 계층 관계를 나타낼 때 사용

- 대댓글 목록과 인기글 목록은 list(목록) 이라는 상위 계층의 하위 카테고리이기 때문에 슬래시로 구분해주었습니다.

 

 

이렇게 작성한 boardController의 전체 매핑은 다음과 같습니다.

 

---

 

응답객체 만들기

 

컨트롤러를 RestController로 작성하면, 데이터 자체를 그대로 리턴할 수도 있습니다.

그러나 REST API는 상태코드를 같이 반환하는 것이 좋습니다.

따라서 HTTP 응답 상태코드와 데이터를 함께 반환할 수 있는 응답클래스를 만들고, 데이터들을 이 응답객체에 담아서 반환하도록 만들었습니다.

 

APIResponse

생성자를 오버로딩 하여 기본 생성자에는 OK(200)번 코드를 담고, HttpStatus를 직접 넣어줄 수도 있도록 만들었습니다.

응답데이터의 타입은 Map객체로 설정하여, 반환할 데이터를 key value쌍으로 담을 수 있도록 하였습니다.

 

---

 

문서 커스터마이징

 

Swagger에서 제공하는 어노테이션으로 UI에 표시되는 설명들을 직접 지정할 수 있습니다.

 

 

따라서 컨트롤러마다 API의 제목과 상세 설명, 요구하는 파라미터의 타입 및 설명, 필수옵션 여부를 지정해 두었습니다.

다른 사람이 이용하기 쉽도록 최대한 직관적으로 작성하였습니다.

 

---

SQL쿼리를 작성 후 매퍼 인터페이스에 등록하고, 비즈니스 로직을 수행하는 서비스 메소드를 작성 후, 컨트롤러에서 호출하는 과정은 Controller를 사용했을 때와 동일합니다.

 

이렇게 Wee.T의 커뮤니티 부분은 모두 REST API로 개발하였습니다.

전체글 목록 조회 / 인기글 목록 조회 / 게시글 상세 조회 / 임시저장 목록 조회 / 대댓글 목록 조회

게시글 작성 / 댓글 작성 / 대댓글 작성

게시글 수정 / 댓글 수정 

게시글 삭제 / 댓글 삭제

게시글 추천 / 게시글 추천 취소

댓글 채택 / 조회수 업데이트 / 게시글 추천여부 조회

 

클라이언트에서는 Ajax 통신을 사용하여 데이터들을 알맞게 가공하여 화면에 뿌려주었습니다.