API 문서화: Swagger/OpenAPI

// build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("OHS API")
                .version("v1.0")
                .description("OPEN HYPER STEP REST API"))
            .components(new Components()
                .addSecuritySchemes("bearerAuth",
                    new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")
                ))
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
    }
}

@RestController
@RequestMapping("/api/users")
@Tag(name = "User", description = "사용자 관리 API")
@RequiredArgsConstructor
public class UserController {
    private final UserService userService;

    @Operation(summary = "사용자 조회", description = "ID로 단일 사용자 조회")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "성공",
            content = @Content(schema = @Schema(implementation = UserDto.class))),
        @ApiResponse(responseCode = "404", description = "사용자 없음",
            content = @Content(schema = @Schema(implementation = ProblemDetail.class)))
    })
    @GetMapping("/{id}")
    public UserDto getUser(
        @Parameter(description = "사용자 ID", example = "1", required = true)
        @PathVariable Long id
    ) {
        return userService.findById(id);
    }

    @Operation(summary = "사용자 등록")
    @PostMapping
    public ResponseEntity<UserDto> create(
        @Valid @RequestBody
        @io.swagger.v3.oas.annotations.parameters.RequestBody(
            description = "사용자 등록 정보",
            required = true,
            content = @Content(schema = @Schema(implementation = SignupRequest.class))
        )
        SignupRequest req
    ) {
        return ResponseEntity.status(HttpStatus.CREATED)
            .body(userService.signup(req));
    }
}

@Schema(description = "사용자 정보")
public record UserDto(
    @Schema(description = "사용자 ID", example = "1")
    Long id,

    @Schema(description = "이메일", example = "alice@example.com")
    String email,

    @Schema(description = "이름", example = "Alice")
    String name,

    @Schema(description = "권한", example = "USER",
            allowableValues = {"USER", "ADMIN"})
    String role,

    @Schema(description = "가입일")
    LocalDateTime createdAt
) {}


@Schema(description = "회원가입 요청")
public record SignupRequest(
    @Schema(description = "이메일", example = "alice@example.com")
    @NotBlank @Email
    String email,

    @Schema(description = "비밀번호 (8자+, 대문자+숫자)", example = "Pass1234")
    @NotBlank @Pattern(regexp = "^(?=.*[A-Z])(?=.*\d).{8,}$")
    String password,

    @Schema(description = "이름", example = "Alice")
    @NotBlank @Size(min = 2, max = 50)
    String name
) {}

# application.yml
springdoc:
  api-docs:
    path: /api-docs
    enabled: true
  swagger-ui:
    path: /swagger
    operations-sorter: alpha
    tags-sorter: alpha
    try-it-out-enabled: true

# application-prod.yml — 프로덕션은 비활성
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

@Bean
public GroupedOpenApi userApi() {
    return GroupedOpenApi.builder()
        .group("user")
        .pathsToMatch("/api/users/**")
        .build();
}

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
        .group("admin")
        .pathsToMatch("/api/admin/**")
        .build();
}