[Spring Boot] Springdoc-OpenApi ( Swagger )

 

 

build.gradle

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'

 

 

 

• springdoc-openapi-starter-webmvc-ui를 사용하면 Swagger UI를 통해 REST API 문서를 시각적으로 확인할 수 있습니다.

@RestController
@RequestMapping("/api/v1")
@Slf4j
public class ResponseController {

    // http://localhost:8888/api/v1

    @GetMapping("")
    public CustomResponse<UserRequest> user(){

        var user = new UserRequest();
        user.setUsername("홍길동");
        user.setUserAge(10);
        user.setEmail("hong@gmail.com");

        log.info("user: {}", user);

        return CustomResponse.ok("user 객체 생성", user);
    }

    @GetMapping("/test")
    public CustomResponse<UserRequest> user(@RequestParam("name") String name){
        var user = new UserRequest();
        user.setUsername(name);
        user.setUserAge(10);
        user.setEmail("hong@gmail.com");

        log.info("user: {}", user);

        return CustomResponse.ok("user 객체 생성", user);
    }
}

 

 

 

 

 

Swagger annotation

@RestController
@RequestMapping("/api/v1")
@Slf4j
@Tag(name = "Example", description = "Example API")
public class ResponseController {

    // http://localhost:8888/api/v1

    @GetMapping("/test")
    @Operation(summary = "Example API Summary", description = "User Info")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Success",
                    content = {@Content(schema = @Schema(implementation = CustomResponse.class))}),
            @ApiResponse(responseCode = "404", description = "Not Found"),
            @ApiResponse(responseCode = "500", description = "Internal Server Error")
    })
    public UserRequest user(@RequestParam("name") String name,
                            @RequestParam("age") int age
                                            ){
        var user = new UserRequest();
        user.setUsername(name);
        user.setUserAge(age);
        user.setEmail("hong@gmail.com");

        log.info("user: {}", user);

        return user;
    }

}

 

@Tag는 해당 컨트롤러에 대한 설명을 정의한다.

@Operation에서는 각각의 API에 대한 설명을 정의한다.

@ApiResponse에서는 각각의 응답 코드에 따른 케이스를 설명하고 있다. 응답 성공 시 CustomResponse의 형태로 반환함을 알리고 있다.

 

@Data
@AllArgsConstructor
@NoArgsConstructor
@JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class)
@Schema(title = "User : User 정보")
public class UserRequest {

    @Schema(description = "사용자 이름", example = "chan")
    private String username;

    @Schema(description = "사용자 나이", example = "20")
    private int userAge;

    @Schema(description = "사용자 이메일", example = "chan111@naver.com")
    private String email;
}

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Getter;
import org.springframework.http.HttpStatus;

@Getter
public class CustomResponse<T> {

    @Schema(description = "성공 여부", example = "true")
    private boolean success;

    @Schema(description = "응답 메세지", example = "Success")
    private String message;

    @Schema(description = "응답 데이터", example = "Any Data")
    private T data;
}