[Spring Boot] 프로젝트에 Swagger 적용, Swagger 어노테이션 정리

Spring Boot

[Spring Boot] 프로젝트에 Swagger 적용, Swagger 어노테이션 정리

공대생안씨 2024. 5. 11. 15:23

1. Swagger 란 ?

Rest API 를 쉽게 문서화, 관리 가능하게 해주는 오픈소스 프레임워크
UI를 통해서 API를 직접 호출하고 테스트 가능
백엔드-프론트엔드 간에 Swagger를 통해서 편리하게 커뮤니케이션 가능
최근에는 Swagger 대신 OpenAPI 3.0 표준을 지원하는 springdoc-openapi-ui 라이브러리가 더 많이 사용됨

2. 프로젝트에 Swagger 적용

2-1. 예제 프로젝트

회원 등록, 조회 (단건, 전체) 가능
- 프로젝트 간소화를 위해서 DB에 연결하지 않고 단순히 ArrayList에 회원 저장
아래에서 예제 프로젝트 코드 설명

2-1-1. User

@Getter
@AllArgsConstructor
public class User {
    private Long id;
    private String name;
    private String password;
}

id, 이름, 비밀번호를 가짐
id는 1부터 시작해서 1씩 증가할 것

2-1-2. UserAddDto

@Getter
public class UserAddDto {
    private String name;
    private String password;
}

회원 등록 시 데이터 전송을 위한 DTO
이름과 비밀번호 만을 주고 받을 것
id는 넘기지 않아도 자동으로 설정

2-1-3. UserController

@RestController
public class UserController {

    private Long id = 1L;
    private List<User> userList = new ArrayList<>();

    // 회원 등록
    @PostMapping("/user")
    public String addUser(@RequestBody UserAddDto userAddDto) {
        userList.add(new User(id, userAddDto.getName(), userAddDto.getPassword()));
        return id++ + "번 회원 등록 완료";
    }

    // 회원 단건 조회
    @GetMapping("/user/{id}")
    public UserDto findUser(@PathVariable int id) {
        User findUser = userList.get(id-1);
        return new UserDto(findUser.getId(), findUser.getName());
    }

    // 회원 전체 조회
    @GetMapping("/user/list")
    public All findAllUsers() {
        List<UserDto> userDtos = userList.stream()
                .map(m -> new UserDto(m.getId(), m.getName()))
                .collect(Collectors.toList());

        return new All(userDtos.size(), userDtos);
    }


    @Data
    @AllArgsConstructor
    static class All<T> {
        private int count;
        private T userData;
    }

    @Data
    @AllArgsConstructor
    static class UserDto {
        private Long id;
        private String name;
    }

}

DB에 연결하지 않고 arrayList에 회원 정보를 저장
회원 조회 시 비밀번호는 조회되면 안되므로 새로운 UserDto 생성
회원 전체 조회 시 전체 회원 수 또한 반환

2-2. Swagger 적용

2-2-1. build.gradle에 라이브러리 추가

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

springdoc 라이브러리 추가
- SpringDoc : Swagger UI 생성, Swagger 어노테이션 사용하기 위한 라이브러리

라이브러리를 추가하면 http://localhost:8080/swagger-ui/index.html에 접속 가능함

2-2-2. SwaggerConfig 추가

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("Swagger UI - practice") // API의 제목
                .description("Swagger UI 적용 예제") // API에 대한 설명
                .version("1.0.0"); // API의 버전
    }
}

2-2-3. application.yml (선택)

추가적인 설정이 가능함
필수 x, 필요에 따라 설정할 것

springdoc:
  swagger-ui:
    path: /api-test  # Swagger-UI의 경로를 /api-test로 설정

    groups-order: DESC  # 그룹 순서를 내림차순으로 설정 (path, query, body, response 순으로 출력)

    tags-sorter: alpha  # 태그를 알파벳 순으로 정렬

    operations-sorter: method  # 작업을 메서드 순으로 정렬 (delete - get - patch - post - put 순으로 정렬, alpha를 사용하면 알파벳 순으로 정렬 가능)

  paths-to-match:
    - /api/**  # Swagger-UI에 표시할 API의 엔드포인트 패턴

  api-docs:
    path: /api  # API 문서의 경로를 /api로 설정

springdoc: swagger-ui: path: 해당 주소로 swagger-ui 접속 가능함
springdoc: paths-to-match: api의 엔드포인트 페턴 설정
- swagger-ui 에 표시하기 위해서 UserController에 @RequestMapping("/api") 추가함

2-3. Swagger 관련 어노테이션

2-3-1. 어노테이션 적용

예시를 위해서 UserController의 addUser 에 위의 어노테이션 중 일부 적용

@PostMapping("/user")
@Operation(summary = "add user", description = "회원 등록 시 사용되는 api")
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "성공"),
        @ApiResponse(responseCode = "4xx", description = "실패")
})
@Parameters({
        @Parameter(name = "name", description = "이름", example = "홍길동"),
        @Parameter(name = "password", description = "비밀번호", example = "password1234!")
})
public String addUser(@RequestBody UserAddDto userAddDto) {
    userList.add(new User(id, userAddDto.getName(), userAddDto.getPassword()));
    return id++ + "번 회원 등록 완료";
}