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

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++ + "번 회원 등록 완료";
}

 

• @Operation 적용 결과

 

• @ApiResponse 적용 결과

 

• @Parameter 적용 결과

 

 

3. Swagger UI에서 api 테스트

 

• 원하는 api 에서 Try it out 클릭

 

• Request body 에서 파라미터 채우고 Execute 클릭

 

• 테스트 결과

1. Server response

 

2. id가 1인 user 조회 결과

 

3. 전체 회원 조회 결과