BE Setup

BE 세팅 가이드 (Spring Boot + springdoc-openapi)

1. build.gradle 의존성 추가

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:3.1.0'
}

Spring Boot 3.x 사용으로 springdoc 3.x 적용 (Spring Boot 2.x라면 springdoc 2.6.0 사용)

2. application.yml 설정

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui

3. 공통 응답 클래스

// ApiResponse.java
@Schema(description = "공통 성공 응답")
public record ApiResponse<T>(boolean success, T data) {
    public static <T> ApiResponse<T> ok(T data) {
        return new ApiResponse<>(true, data);
    }
}

// ApiError.java
public record ApiError(String code, String message) {}

// ApiErrorResponse.java
@Schema(description = "공통 에러 응답")
public record ApiErrorResponse(boolean success, ApiError error) {
    public static ApiErrorResponse of(String code, String message) {
        return new ApiErrorResponse(false, new ApiError(code, message));
    }
}

4. 컨트롤러 사용 예시

@RestController
@RequestMapping("/api/example")
@Tag(name = "Example", description = "예시 API")
public class ExampleController {

    @GetMapping("/{id}")
    @Operation(summary = "단건 조회")
    public ResponseEntity<ApiResponse<ExampleDto>> getOne(@PathVariable Long id) {
        return ResponseEntity.ok(ApiResponse.ok(/* service 호출 */));
    }

    @PostMapping
    @Operation(summary = "생성")
    public ResponseEntity<ApiResponse<ExampleDto>> create(@RequestBody ExampleRequest request) {
        return ResponseEntity.status(201).body(ApiResponse.ok(/* service 호출 */));
    }
}

5. 확인

서버 실행 후:

• Swagger UI: http://localhost:8080/swagger-ui
• OpenAPI JSON: http://localhost:8080/api-docs

FE 타입 자동 생성 (BE 서버 뜨면)

cd frontend
npm run generate:api   # src/types/api.ts 자동 생성

API 응답 포맷 컨벤션은 API-Response-Convention 참고