Swagger 명세 작업

[MyYeonbi]

`package org.project.backend.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import lombok.RequiredArgsConstructor;
import org.project.backend.dto.LoginRequestDTO;
import org.project.backend.dto.LoginResponseDTO;
import org.project.backend.service.AuthService;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;

@RestController
@RequestMapping("/api/auth")
@requiredargsconstructor
@Api(tags = "Auth API", description = "인증 관련 API") // AuthController 설명 추가
public class AuthController {

private final AuthService authService;

@ApiOperation(value = "로그인", notes = "사용자의 ID와 패스워드를 사용하여 로그인합니다.")
@PostMapping("/login")
public ResponseEntity<LoginResponseDTO> login(
        @ApiParam(value = "로그인 요청 데이터", required = true)
        @Valid @RequestBody LoginRequestDTO loginRequest) {
    // AuthService를 이용하여 로그인 처리
    LoginResponseDTO response = authService.login(loginRequest);
    return ResponseEntity.ok(response);
}

}
`

설명 :

controller와 DTO에서 Swagger 명세에 대해 다듬을 필요가 있다.
특히 swagger로 테스트할 때, id : "string"과 같은 의미 없는 샘플 데이터가 들어가고 있으며,
id는 auto increment 옵션이 있음에도 불구하고 불필요하게 샘플 데이터로 입력되는 경우가 있다.
또한, name: "홍길동", email: "lsy@naver.com"과 같은 과도한 샘플 데이터를 정리해야 한다.

작업 목표 :

1. swagger 명세 정리 :

• controller 및 DTO에 작성된 Swagger 명세를 개선하여 더 정확하고 실제 테스트에 필요한 정보만 기입되도록 수정한다.
• 각 필드에 대한 적절한 설명을 추가하고 불필요한 예시 데이터를 제거한다.

2. 불필요한 샘플 데이터 제거 :

• id와 같은 auto increment필드에 대한 샘플 데이터 제거한다.
• 과도하게 구체적인 샘플 데이터(홍길동, lsy@naver.com 등) 대신 더 일반적인 설명을 사용하여 불필요한 혼란을 방지한다.

세부 작업 항목 :

• AuthController에 있는 login 메서드의 Swagger 명세 정리했다.
• LoginRequestDTO, LoginResponseDTO에서 불필요한 샘플 데이터 제거 및 명세 정리했다.
• Swagger로 테스트할 때 실제 환경과 일치하는 데이터를 사용할 수 있도록 수정했다.

참고 :

이번 수정 작업의 목적은 Swagger 명세가 더 정확하고 간결하게 유지되도록 하여, 개발 및 테스트 과정에서의 혼란을 줄이는 것이다.

[MyYeonbi]

`package org.project.backend.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import lombok.RequiredArgsConstructor;
import org.project.backend.dto.BusinessCardDTO;
import org.project.backend.service.BusinessCardService;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api")
@requiredargsconstructor
@Api(tags = "BusinessCard API", description = "전자 명함 관리 API") // 컨트롤러 설명
public class BusinessCardController {

private static final Logger logger = LoggerFactory.getLogger(BusinessCardController.class);

private final BusinessCardService businessCardService;

@ApiOperation(value = "회원 ID로 새로운 명함 생성", notes = "회원 ID를 사용하여 새로운 전자 명함을 생성합니다.")
@PostMapping("/business-cards/members/{memberId}")
public ResponseEntity<BusinessCardDTO> createBusinessCard(
        @ApiParam(value = "회원 ID", required = true, example = "1") @PathVariable Long memberId,
        @ApiParam(value = "생성할 명함 정보", required = true) @RequestBody BusinessCardDTO businessCardDTO) {
    try {
        BusinessCardDTO createdBusinessCardDTO = businessCardService.createBusinessCard(memberId, businessCardDTO);
        return ResponseEntity.status(HttpStatus.CREATED).body(createdBusinessCardDTO);
    } catch (RuntimeException e) {
        logger.error("Error creating business card", e);
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(null);
    } catch (Exception e) {
        logger.error("Internal server error while creating business card", e);
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
    }
}

@ApiOperation(value = "회원 ID로 명함 조회", notes = "회원 ID를 사용하여 전자 명함을 조회합니다.")
@GetMapping("/business-cards/members/{memberId}")
public ResponseEntity<BusinessCardDTO> getBusinessCardByMemberId(
        @ApiParam(value = "회원 ID", required = true, example = "1") @PathVariable Long memberId) {
    try {
        BusinessCardDTO businessCardDTO = businessCardService.getBusinessCardByMemberId(memberId);
        return ResponseEntity.ok(businessCardDTO);
    } catch (RuntimeException e) {
        logger.error("Business card not found for member ID: {}", memberId, e);
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(null);
    } catch (Exception e) {
        logger.error("Internal server error while retrieving business card", e);
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
    }
}

@ApiOperation(value = "명함 정보 업데이트", notes = "명함 ID와 업데이트할 정보를 사용하여 전자 명함을 업데이트합니다.")
@PutMapping("/business-cards/{cardId}")
public ResponseEntity<BusinessCardDTO> updateBusinessCard(
        @ApiParam(value = "명함 ID", required = true, example = "1234-5678") @PathVariable String cardId,
        @ApiParam(value = "업데이트할 명함 정보", required = true) @RequestBody BusinessCardDTO businessCardDTO) {
    try {
        BusinessCardDTO updatedBusinessCardDTO = businessCardService.updateBusinessCard(cardId, businessCardDTO);
        return ResponseEntity.ok(updatedBusinessCardDTO);
    } catch (RuntimeException e) {
        logger.error("Business card not found with ID: {}", cardId, e);
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(null);
    } catch (Exception e) {
        logger.error("Internal server error while updating business card", e);
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
    }
}

}`

설명 :

현재 BusinessCardController에서 Swagger 명세가 작성되어 있지만, 일부 샘플 데이터가 지나치게 구체적이거나 불필요한 데이터로 기입되어 있어, Swagger 문서의 효율성을 저해하고 있다. 이를 해결하기 위해 명세를 정리하고 불필요한 샘플 데이터를 제거하는 작업이 필요하다.

작업 목표:

1. Swagger 명세 정리 :

• BusinessCardController 내의 각 메서드에서 Swagger 명세를 다듬어, 의미 없는 샘플 데이터 및 설명을 제거하고 실제 테스트 환경에서 유효한 데이터로 대체한다.
• @apioperation,@ApiParam 어노테이션의 설명을 더 명확하게 작성하여 API 사용자들이 이해하기 쉽게 수정한다.

2. 불필요한 샘플 데이터 제거 :

• 예시로 제공되는 회원 ID : 기존에 있던 샘플 데이터 대신 더 일반적인 예시로 수정하여 혼란을 방지했다.
• DTO의 데이터 구조가 너무 구체적이거나 실제 API테스트에 적합하지 않은 경우 샘플 데이터를 최소화하거나 제거한다.

세부 작업 항목 :

• createBusinessCard 메서드에서 @ApiParam의 예시 값 정리 (예 : ID : "1" -> 회원 ID : "123")
• getBusinessCardByMemberId 메서드에서 @ApiParam의 예시 값 정리
• updateBusinessCard 메서드에서 @ApiParam의 예시 값 정리 및 설명 추가
• DTO의 필드에 대한 swagger명세가 필요하면 추가 작업 (예: BusinessCardDTO 명세 추가)

참고 :

이 작업은 Swagger문서를 더 이해하기 쉽게 다듬고, API테스트 시 의미 잇는 데이터로 교체하여 개발 및 테스트 과정에서의 혼란을 최소화하는 것을 목표로 한다.

[MyYeonbi]

`package org.project.backend.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import lombok.RequiredArgsConstructor;
import org.project.backend.dto.DocumentDTO;
import org.project.backend.exception.document.DocumentNotFoundException;
import org.project.backend.service.DocumentService;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/document")
@requiredargsconstructor
@Api(tags = "Document API", description = "문서 관리 API")
public class DocumentController {
private final DocumentService documentService;

@ApiOperation(value = "회원 ID로 새로운 문서 생성", notes = "회원 ID를 사용하여 새로운 문서를 생성합니다.")
@PostMapping("/create/{memberId}")
public ResponseEntity<DocumentDTO> createDocument(
        @ApiParam(value = "회원 ID", required = true, example = "1") @PathVariable Long memberId) {
    try {
        DocumentDTO createdDocument = documentService.createDocument(memberId);
        return ResponseEntity.status(HttpStatus.CREATED).body(createdDocument);
    } catch (IllegalStateException e) {
        return ResponseEntity.status(HttpStatus.CONFLICT).body(null); // 중복된 Document
    } catch (DocumentNotFoundException e) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(null); // Document 없음
    } catch (Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null); // 서버 에러
    }
}

@ApiOperation(value = "회원 ID로 문서 조회", notes = "회원 ID를 사용하여 문서를 조회합니다.")
@GetMapping("/get/{memberId}")
public ResponseEntity<DocumentDTO> getDocument(
        @ApiParam(value = "회원 ID", required = true, example = "1") @PathVariable Long memberId) {
    try {
        DocumentDTO documentDTO = documentService.getDocumentByMemberId(memberId);
        return ResponseEntity.ok(documentDTO);
    } catch (DocumentNotFoundException e) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(null);
    } catch (Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
    }
}

}

package org.project.backend.dto;

import io.swagger.annotations.ApiModelProperty;
import lombok.*;

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@builder
public class DocumentDTO {
@ApiModelProperty(value = "회원 ID", example = "1")
private Long memberId;

@ApiModelProperty(value = "문서 고유번호", example = "100")
private Long documentId;

@ApiModelProperty(value = "주민등록 정보", example = "{...}") // DTO를 포함한 설명
private ResidentRegistrationDTO RRN;

@ApiModelProperty(value = "운전면허 정보", example = "{...}")
private DriverLicenseDTO DLN;

@ApiModelProperty(value = "여권 정보", example = "{...}")
private PassportDTO PN;

@ApiModelProperty(value = "국제학생증 정보", example = "{...}")
private InternationalStudentIdentityCardDTO ISIC;

@ApiModelProperty(value = "여행 보험 증명서", example = "https://example.com/travelInsurance.jpg")
private String TIC;

@ApiModelProperty(value = "예방 접종 증명서", example = "https://example.com/vaccineCertificate.jpg")
private String VC;

@ApiModelProperty(value = "출입국 사실 증명서", example = "https://example.com/immigrationCertificate.jpg")
private String IC;

}`

설명:

DocumentController 및 관련 DTO에 작성된 Swagger 명세가 구체적이긴 하지만,
일부 샘플 데이터가 지나치게 구체적이거나 불필요한 예시로 들어가 있었다.
이를 수정하여 Swagger 명세가 더 깔끔하고 유용하게 변경될 필요가 있었다.
특히, 문서와 관련된 민감한 정보가 포함된 부분에서 너무 상세한 예시가 들어가 있거나 복잡한 DTO 구조가 포함되어 있으므로 이를 개선할 필요가 있었다.

작업 목표:

1.	Swagger 명세 정리:
•	DocumentController와 관련된 메서드들의 Swagger 설명을 개선하여 더 명확한 정보를 제공한다.
•	DTO의 민감한 정보는 과도한 구체적 예시를 피하고 간단한 예시로 대체하여 사용자에게 불필요한 혼란을 줄인다.
2.	불필요한 샘플 데이터 정리 및 축소:
•	DocumentDTO에서 민감한 정보나 너무 구체적인 정보 예시를 축소하여 보안성을 높이고 간단하게 처리한다.
•	문서 생성 및 조회 관련 Swagger 명세에서 ID와 관련된 샘플 값들을 보다 일반적인 값으로 수정한다.

세부 작업 항목:

•	DocumentController의 createDocument 및 getDocument 메서드에서 @ApiParam의 예시 값 개선 (회원 ID: "1" -> 회원 ID: "123")
•	DocumentDTO에서 주민등록 정보(RRN), 운전면허 정보(DLN), 여권 정보(PN) 등 DTO 내부의 설명을 간단하게 다듬기 ({...}로 축소 표기된 부분을 간단한 문자열로 수정 또는 실제 API와 연관된 기본 샘플로 대체)
•	문서 고유번호 및 기타 증명서 관련 필드(TIC, VC, IC)의 예시 URL을 더 명확하고 간단한 형태로 수정.

참고:
DTO 내 포함된 민감한 정보는 실제 데이터를 사용하지 않고 더 일반적인 형식으로 수정하며, Swagger 문서의 가독성을 높이는 것이 이 작업의 주요 목적이었다.