Swagger Convention

논의 내용
규칙

☑️ 최종 예시 - Controller

package com.example.member.api;

  import com.example.member.dto.MemberResponse;
  import com.example.member.dto.MemberSearchRequest;
  import com.example.common.dto.ErrorResponse;
  import io.swagger.v3.oas.annotations.Operation;
  import io.swagger.v3.oas.annotations.Parameter;
  import io.swagger.v3.oas.annotations.media.ArraySchema;
  import io.swagger.v3.oas.annotations.media.Content;
  import io.swagger.v3.oas.annotations.media.Schema;
  import io.swagger.v3.oas.annotations.responses.ApiResponse;
  import io.swagger.v3.oas.annotations.responses.ApiResponses;
  import io.swagger.v3.oas.annotations.tags.Tag;
  import org.springdoc.core.annotations.ParameterObject;
  import org.springframework.data.domain.Pageable;
  import org.springframework.data.web.PageableDefault;
  import org.springframework.http.ResponseEntity;
  import org.springframework.web.bind.annotation.*;

  import java.util.List;

  @Tag(name = "Member", description = "회원 관련 API")
  @RestController
  @RequestMapping("/api/members")
  public class MemberController {

      @Operation(
          summary = "회원 목록 조회",
          description = "가족 ID 기준 활성 회원 목록을 조회한다. page는 0부터 시작, size 기본값은 20, sort 형식은 '필드명,asc|desc' 이다."
      )
      @ApiResponses({
          @ApiResponse(responseCode = "200", description = "조회 성공"),
	        @ApiResponse(responseCode = "404", description = "가족 정보가 존재하지 않음"),
	        @ApiResponse(responseCode = "500", description = "서버 오류"),
            
      })
      @GetMapping
      public ResponseEntity<List<MemberResponse>> getMembers(
          @Parameter(description = "가족 ID", example = "10")
          @RequestParam Long familyId,
          @Parameter(description = "회원 상태", example = "ACTIVE")
          @RequestParam(defaultValue = "ACTIVE") String status,
          @ParameterObject
          @PageableDefault(size = 20, sort = "createdAt")
          Pageable pageable
      ) {
          return ResponseEntity.ok(List.of());
      }

      @Operation(
          summary = "회원 단건 조회",
          description = "memberId로 회원 상세를 조회한다. 존재하지 않으면 404를 반환한다."
      )
      @ApiResponses({
          @ApiResponse(responseCode = "200", description = "조회 성공"),
	        @ApiResponse(responseCode = "404", description = "가족 정보가 존재하지 않음"),
	        @ApiResponse(responseCode = "500", description = "서버 오류"),
      })
      @GetMapping("/{memberId}")
      public ResponseEntity<MemberResponse> getMember(
          @Parameter(description = "회원 ID", example = "1")
          @PathVariable Long memberId
      ) {
          return ResponseEntity.ok(new MemberResponse());
      }
  }

</aside>

☑️ 최종 예시 - DTO

package com.example.member.dto;

  import io.swagger.v3.oas.annotations.media.Schema;
  import lombok.Getter;
  import lombok.Setter;

  @Getter
  @Setter
  @Schema(description = "회원 생성 요청 DTO")
  public class MemberCreateRequest {

      @Schema(description = "가족 ID", example = "10")
      private Long familyId;

      @Schema(description = "회원 이름", example = "홍길동")
      private String name;

      @Schema(description = "회원 상태", example = "ACTIVE")
      private String status;
  }

</aside>

☑️ 단건 응답 DTO

@Schema(description = "회원 응답 DTO")
public class MemberResponse {

    @Schema(description = "회원 ID", example = "1")
    private Long id;

    @Schema(description = "회원 이름", example = "홍길동")
    private String name;

    @Schema(description = "회원 상태", example = "ACTIVE")
    private String status;
}

</aside>

☑️ 페이지 응답 DTO

@Schema(description = "회원 페이지 응답 DTO")
public class MemberPageResponse {

    @Schema(description = "회원 목록")
    private List<MemberResponse> content;

    @Schema(description = "현재 페이지", example = "0")
    private int page;

    @Schema(description = "페이지 크기", example = "10")
    private int size;

    @Schema(description = "전체 요소 수", example = "25")
    private long totalElements;
}

</aside>

☑️ 공통 에러 응답 DTO

@Schema(description = "공통 에러 응답")
public class ErrorResponse {

    @Schema(description = "에러 코드", example = "MEMBER_NOT_FOUND")
    private String code;

    @Schema(description = "에러 메시지", example = "회원이 존재하지 않습니다.")
    private String message;

    @Schema(description = "에러 발생 시간", example = "2026-02-19T12:00:00")
    private String timestamp;
}

</aside>