Swagger 구현

[pykido]

📝 이슈 설명

API가 많아지면서 POSTMAN으로 전부 테스트해보기엔 다소 불편한 사항이 있을 수 있다고 생각되었습니다! 따라서 swagger를 도입하려고 합니다.

1. Gradle 의존성 추가
   • SpringDoc OpenAPI는 별도의 추가 설정 없이는 일단 기본적으로 경로가 /swagger-ui.html 입니당!
   • 애플리케이션 실행하고, 브라우저에서 http://localhost:8080/swagger-ui.html로 이동하여 API 문서 확인 가능해요!

     dependencies {
     // SpringDoc OpenAPI (Swagger UI 포함)
     implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'
     }

2. 모든 컨트롤러에 API 설명 추가
   • 컨트롤러 레이어에 Swagger 적용해야 합니다.
   • @Tag, @Operation 추가 부탁드립니다!

@Tag(name = "[관리자] 보호자 (Guardian)", description = "보호자 정보 조회 및 수정")
@PreAuthorize("hasAnyAuthority('ROLE_SUPERMAN', 'ROLE_ADMIN')")
@RestController
@RequestMapping("/v1/admin/guardian")
@RequiredArgsConstructor
public class GuardianAdminController {

    private final GuardianService guardianService;

    @Operation(summary = "보호자 정보 상세 조회")
    @GetMapping("/{guardianId}")
    public ResponseEntity<GuardianResponse> showOneGuardian(
        @PathVariable("guardianId") Long guardianId) {
        GuardianResponse guardianResponse = guardianService.getGuardianById(guardianId);
        return ResponseEntity.ok(guardianResponse);
    }
    ....
}

3. Swagger 기본 설정 추가

   • 보호자, 돌봄대상자와 같이 도메인별로 API 문서를 나누면 좋을 듯합니다! 참고 코드

     
     @Configuration
     public class OpenApiConfiguration {

   @Bean public OpenAPI openAPI() { Info info = new Info() .title("돌봄다리 API Document") .version("v1.0.0") .description("돌봄다리 서버 API 명세서입니다."); return new OpenAPI() .components(new Components()) .info(info); }

   @Bean public GroupedOpenApi allApi() { return GroupedOpenApi.builder() .group("all") .displayName("All API") .pathsToMatch("/**") .build(); }

   @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group("guardian") .displayName("Guardian API") .pathsToMatch("/v*/guardian/**") .build(); }

   
   4. Swagger UI 커스터마이징 (선택)
   - 요건 선택사항이긴 한데 필요하다면 해주세요~!!

   springdoc: api-docs: enabled: true # API 문서화 활성화 여부 path: /api-docs # OpenAPI 문서의 경로를 설정 (기본: /v3/api-docs) swagger-ui: path: /swagger-ui.html # Swagger UI 경로 설정 (기본: /swagger-ui.html) operationsSorter: method # API 목록을 정렬하는 방식 (method로 정렬) display-request-duration: true # 요청 시간 표시 defaultModelsExpandDepth: -1 # 모델 확장 방지 (Swagger UI에서 모델이 펼쳐지지 않음) tryItOutEnabled: true # Try it out 버튼 활성화 (API 테스트 가능) doc-expansion: none # Swagger UI의 기본 확장 상태 (none으로 설정 시 모두 접힌 상태) deep-linking: true # URL에서 특정 엔드포인트로 바로 연결 가능

☑️ TODO

• [x] Gradle 의존성 추가
• [x] 모든 컨트롤러에 API 설명 추가
• [x] Swagger 기본 설정 추가
• [x] Swagger UI 커스터마이징 (선택)
• [x] 애플리케이션 실행 후 스웨거에 접속하여 API 테스트해보기

[hyyyh0x]

@Schema(description = "상품 이름", example = "춘식이 잠옷") 이런식으로 dto request에는 따로 달 필요 없을까요?

[pykido]

필수는 아니지만 달아도 좋을 거 같아요~!