😁 배운 내용

이미 설계가 완료된 Domain과 연관된 새로운 Domain이 추가 됐을 때 변경 사항과 발생하는 문제를 하나씩 해결해 볼 수 있었던 경험이었습니다!

✏️ 미션 제출

미션 전체 코드는 다음 PR에서 살펴볼 수 있습니다.
[이호석] DAY7 상점 도메인 추가 및 swagger 설정(완료)

✅ 상점 테이블 설계

• Store 도메인은 id, 상점 이름, 주소, 전화번호를 가집니다. (필드 정의)
• 주소에는 도로명 주소와 상세 주소가 포함됩니다. (주소 -> 값 타입 객체)
• 하나의 상점은 여러 개의 상품을 가질 수 있습니다. (연관관계 1:N)

따라서 다음과 같이 Entity 객체를 만들 수 있습니다.

N 측 개체가 외래키를 갖게 되므로 연관관계 주인은 Product가 됩니다. 따라서 Store의 products 필드에 mappedBy를 통해 연관관계의 주인에게 존재하는 연관관계 객체의 필드명을 입력합니다.

Product 또한 연관관계에 대한 매핑을 추가해주어야 합니다.

외에 dto 및 테스트 클래스들에 대한 변경 지점들은 생략합니다.

[self 연습] 요구사항 추가

• 상품은 반드시 상점에 속해 있어야 한다.

위 요구사항은 기존 상품 등록 로직에 변화를 요구합니다.
상품 저장 이전에 상품 저장 dto의 storeId를 통해 상점 도메인을 찾아와 상품 도메인에 등록시켜주어야 합니다. 또한 양방향 연관관계를 갖으므로 상점의 상품 리스트에도 추가해주면 좋을 것 같습니다!

dto의 storeId를 통해 찾아온 store 객체를 product에 지정합니다. 이후 createProduct를 통해 도메인 객체로 변경합니다.

Product 도메인을 생성한 후, 상점의 상품 목록에도 생성한 상품을 추가해줍니다.

✅ 상점 관련 기본 api 구현하기

상점 등록 api

• StoreController
  

• StoreService
  

전체 상점 조회 api

• StoreController
  

• StoreService
  

상세 상점 조회 (id별) api

• StoreController
  

• StoreService
  

하나의 상점에 속하는 모든 상품 조회 api

• ProductController
  

• ProductService
  

JPA는 외래키가 아닌 객체를 통해 조회할 수 있다.

✅ 지금까지 개발한 api들에 대한 swagger 생성하기

지원 중단된 springfox가 아닌 springdoc-openapi-ui를 사용했습니다.

의존관계, yml 설정

implementation 'org.springdoc:springdoc-openapi-ui:1.6.8'

참고로 테스트용 db를 h2 in-memory-db를 이용하므로 테스트 yml 파일에도 설정을 추가해주어야 합니다.

@ApiResponse의 중복 코드 제거를 위한 커스텀 어노테이션 추가

@ApiResponse를 직접적으로 Controller에 작성하다 보면 동일한 응답에 대해서 중복적인 작성이 요구된다. 따라서 응답을 모아두는 커스텀 어노테이션을 통해 컨트롤러에서의 중복되는 코드를 최소화할 수 있다.

이때 responseCode 옵션은 Constant 문자열만 입력될 수 있습니다. StatusCode는 상수를 가진 클래스 입니다!

Controller에서 적용시켜보기

• @Tag: 해당 컨트롤러에 대한 이름과 설명이 추가됩니다.
• @ApiDocumentResponse: 커스텀 어노테이션으로 해당 어노테이션의 알맞은 @ApiResponse를 통해 api 문서가 생성됩니다.
• @Operation: summary는 api에 대한 간략한 설명을 description은 api에 대한 상세 설명을 나타냅니다. (외에도 추가적인 옵션이 많음)

Swagger api 예시를 좀 더 이해하기 편하게 하기 위한 응답값 설정

위의 StoreResponse에 대해 추가적인 @Schema 설정을 통해 자세한 api 문서를 생성할 수 있습니다.

@Schema의 description은 해당 필드에 대한 설명을 보여주며 example은 실제 api 문서에 표시될 예제의 데이터로 나타납니다. Address는 값 객체이므로 @Schema의 example설정을 Address에게 직접 설정해야 api의 응답값 예시가 Address의 필드까지 포함됩니다.

Swagger ui 생성

Swagger ui 3.X 버전부터는 다음과 같은 주소 포멧을 가집니다
http://server:port/swagger-ui/index.html
따라서 http://localhost:8080/swagger-ui/index.html에 접속하면 다음과 같이 자동 생성된 api문서를 볼 수 있습니다.

위에서 설명한 /api/stores/{storeId}에 대해 생성된 api 응답도 다음과 같습니다.

🤔 개선 및 고민되는 부분들

Swagger보다는 Spring Rest docs를 사용하는것이 좋다는 말을 많이 들어왔습니다.

단순히 Controller에서 적용되는 코드가 복잡하기에 순수 로직을 알아보기 어렵다는 말만 들어왔었지만, 이번 미션에서 실제 Swagger를 사용해보며 많은 불편함을 느꼈습니다.. api 문서를 생성하는데 들어가는 시간과 비용이 상당히 큰것도 문제였고, 개인적으로 응답값이 추가될때마다 설정을 해주는 부분도 마음에 들지 않았습니다.

다음번엔 Spring Rest Docs를 사용해보며 기존 Swagger 코드를 걷어내보려고 합니다!