I. Swagger 3.0

Swagger는 많은 편리한 기능을 제공하지만, 친절하다고는 할 수 없습니다. Swagger Documentation에서 여러 정보를 확인할 수 있지만, 프로젝트에 실질적으로 Swagger의 어떤 기능을 어떻게 접목시킬지 판단하는 것은 쉽지 않습니다. 이틀 간 Swagger Documentation을 확인하고, Test들을 진행하면서 Swagger 적용 방향을 정리하였으니 프로젝트 진행 간 꼭 참고해주시기 바랍니다.🙏

II. Convention

1. DTO

저희 프로젝트는 DTO를 크게 3가지로 분류하고 있습니다.

  1. Request DTO: Controller에서 사용되며, @RequestBody를 통해 Request의 Data를 받아오는 DTO
  2. Service DTO: Service에서 사용되며, 실제 비즈니스 로직의 적용 대상이 되는 DTO
  3. Response DTO: Service에서 Controller로 반환되며, 요청에 대한 결과 Data를 가지고 있는 DTO

위 세 가지 DTO 중에서 API Document에 명시되어야 할 DTO는 **Request DTO, Response DTO**입니다. 왜나하면 FE와 공유해야할 정보는, 어떤 Request가 필요하고 어떤 Response를 줄지가 전부이기 때문입니다!(😕말이 좀 이상하네요ㅠ)

1. @Schema

Swagger에서 어떤 객체의 형태를 지정할 때는, @Schema 를 사용합니다. 사용 예시는 다음과 같습니다.

위 예시에서 사용한 @Schema 옵션말고도, 다양한 옵션이 준비되어있습니다. 자세한 내용은 Supported JSON Schema Keywords (swagger.io)을 확인해주세요!

2. Controller

사실 Swagger의 설정은 대부분 Controller에 몰려있습니다. 적용이 어렵지는 않으니, 하나씩 천천히 따라해보시면 좋을 것 같습니다!

<aside> 🔥 Swagger 적용을 위해, 각 컨트롤러 메소드의 반환 타입을 명확하게 설정해야합니다!

</aside>

SuccessResponse가 제네릭 타입의 Field를 가지고 있기 때문에, 좀 더 세세하게 반환 형식을 Swagger에게 알려주기 위한 작업입니다.😀