spring boot REST API Web 프로젝트 (3) - API 관리를 위한 Swagger 적용

스프링 부트 REST API WEB 프로젝트

깃헙 링크

https://github.com/choiwoonsik/springboot_RestApi_App_Project/tree/main/restApiSpringBootApp

수행 목록

1. 환경구성 및 helloworld 출력
2. H2 DB 연동
3. Swagger API 문서 연동
4. REST API 설계
5. RestControllerAdvice를 이용한 통합 예외 처리
6. Entity - DTO 분리
7. MessageSource를 이용해 예외 메시지 다국화
8. JPA Aduting을 이용해 객체 생성시간/수정시간 적용
9. 스프링 시큐리티 + Jwt를 이용해서 인증 및 권한 체크
10. 스프링 시큐리티 AuthenticationEntryPoint, AccessDenied로 인증 및 인가 예외처리
11. Jwt AccessToken + RefreshToken으로 보안성과 사용자 편의성 고도화하기
12. JUnit Test (단위 테스트)
13. JUnit Test (통합 테스트)
14. OAuth 2.0 정리
15. OAuth 2.0 카카오 로그인 part.1 Authorization code + Token 발급
16. OAuth 2.0 카카오 로그인 part.2 토큰으로 회원 가입 / 로그인
17. OAuth 2.0 카카오 로그인 테스트 검증
18. 환경별 설정을 위해서profile 분리하기 

---

Swagger를 통해 API 문서 자동화

현재는 api 테스트를 위해 postman를 설치해서 진행하고 있었다. 하지만 swagger라는 문서 자동화 툴을 사용하면 테스트 가능한 Web UI를 지원하고, 자동으로 API Documents를 생성해주므로 편리하게 api 문서를 생성할 수 있다.

 

Build.gradle에 swagger 의존성 추가

implementation 'io.springfox:springfox-swagger2:2.6.1'
implementation 'io.springfox:springfox-swagger-ui:2.6.1'

 

config package 생성 후 SwaggerConfiguration 클래스 생성

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket SwaggerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerInfo()) // API Docu 및 작성자 정보 매핑
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.restApi.restApiSpringBootApp.controller"))
                .paths(PathSelectors.any()) // controller package 전부
                //.paths(PathSelectors.ant("/v1/**"))  // controller 패키지 내 v1만 택해서 할수도 있다.
                .build()
                .useDefaultResponseMessages(false); // 기본 세팅값인 200, 401, 402, 403, 404를 사용하지 않는다.
    }

    private ApiInfo swaggerInfo() {
        return new ApiInfoBuilder().title("Spring API Documentation")
                .description("앱 서버 API 설명을 위한 문서입니다.")
                .license("woonsik")
                .licenseUrl("ws-pace.tistory.com")
                .version("1")
                .build();
    }
}

 

UserController에 적용시키기

@Api(tags = {"1. User"})
@RequiredArgsConstructor
@RestController
@RequestMapping("/v1")
public class UserController {

    private final UserJpaRepo userJpaRepo;

    @ApiOperation(value = "모든 회원 조회", notes = "모든 회원 목록을 조회합니다.")
    @GetMapping("/users")
    public List<User> findAllUser() {
        return userJpaRepo.findAll();
    }

    @ApiOperation(value = "회원 등록", notes = "회원을 등록합니다.")
    @PostMapping("/user")
    public User save(@ApiParam(value = "회원 이메일", required = true) @RequestParam String email,
                     @ApiParam(value = "회원 이름", required = true) @RequestParam String name) {
        User user = User.builder()
                .email(email)
                .name(name)
                .build();

        return userJpaRepo.save(user);
    }

    @ApiOperation(value = "회원 검색 (이름)", notes = "이름으로 회원을 검색합니다.")
    @GetMapping("/findUserByName/{name}")
    public List<User> findUserByName(@ApiParam(value = "회원 이름", required = true) @PathVariable String name) {
        return userJpaRepo.findByName(name);
    }

    @ApiOperation(value = "회원 검색 (이메일)", notes = "이메일로 회원을 검색합니다.")
    @GetMapping("/findUserByEmail/{email}")
    public User findUserByEmail(@ApiParam(value = "회원 이메일", required = true) @PathVariable String email) {
        return userJpaRepo.findByEmail(email);
    }
}

@Api(tags = {"1. User"})

• 제목 역활을 한다

@ApiOperation(value = "모든 회원 조회", notes = "모든 회원 목록을 조회합니다.")

• value는 리스트로 봤을 때 간단하게 보이는 용도
• notes는 펼쳐봤을 때 자세히 알려주는 용도

@ApiParam(value = "회원 이메일", required = true) @RequestParam String email

• ApiParam은 Swagger에서 설명을 붙이기 위한 용도이다. value는 설명, required는 필수값 설정 여부
• @RequestParam은 HTTP GET 메소드에서 매칭되는 request parameter값이 자동으로 들어간다.
  • url뒤에 쿼리로 붙는 값을 가져올 때 사용한다
  • https://localhost:8080/user?name=woonsik&email=dnstr@email.com
  • @RequestParam("{vlaue}") : {value}가 실제로 전달하는 인자의 이름이 된다. -> "{value}=값"
• @PathVariable도 HTTP 요청에서 매칭되는 request parameter값이 자동으로 들어간다.
  • 단, 쿼리가 아니라 url에 추가되어서 전달된다.
  • http://localhost:8080/v1/findUserByName/woonsik
  • REST API에서 값을 호출할 때 주로 많이 사용한다. (Ex. schedule/{lck, lck_cl ...})

정상적으로 작동될 뿐만 아니라 실제로 적용해서 테스트를 해보면 postman을 사용할 때보다 훨씬 직관적이고 친절하고 편리하다. 앞으로도 프로젝트를 진행할 때 적극적으로 적용시켜서 해야겠다.