Swagger

Swagger

Swagger 는 REST API 를 문서화하고, 웹 UI 를 통해서 테스트까지 할 수 있게 도와주는 도구입니다.

 

Swagger 는 API 의 메뉴판이라는 말도 있습니다.

개발자가 만든 API(서버 기능 목록) 을 정리해서 보여주며, 웹 화면으로 API 를 직접 눌러보고 테스트 할 수 있습니다.

또한 문서를 따로 쓰지 않아도 코드에 따라 자동으로 만들어줍니다.

즉, Swagger = API 메뉴판 + 테스트 도구 

 

사용하는 이유

 

예를 들어, 개발자가 "로그인 API" 를 만들었다고 해봅시다.

 

API 주소: POST /login

요청(Request): id, password

응답(Response): 200 성공, 400 실패 

 

위와 같은 요구사항이 발생했을 때 문서로 정리를 하지 않는다면 팀원들이 헷갈려서 서로 물어봐야 하는 비용 문제가 발생하게 됩니다. 또한 Swagger 를 사용하면 손쉽게 테스트도 해보고 궁금한 부분은 Swagger 에 설정한 설명들을 바탕으로 다시 테스트를 할 수 있습니다.

 

Swagger 사용법

일단 Swagger 을 사용하기 위해서는 build.gradle 파일에 한줄만 추가하시면 됩니다.

Spring boot, build.gradle 을 사용하고 있다고 가정하고 설명하겠습니다.

implementation 'org.springdoc:springdoc-openapi-stater-webmvc-ui:2.8.13'

 

그리고 프로젝트를 실행한 후에 웹 브라우저에서 아래 주소로 들어가면 Swagger 를 사용할 수 있습니다.

http://localhost:8080/swagger-ui/index.html

 

해당 주소로 접속을 하면 개발자가 만든 API 가 자동으로 문서화 된 것을 볼 수 있습니다.

 

Swagger 사용시 주의점

Swagger 사용시 주의해야 할 점은 버전 문제입니다.

Spring 2.x Version 을 사용하고 있는 개발자라면 springdoc 버전의 Swagger 을 설치하면 안되고 springfox 버전의 Swagger 를 설치하셔야 합니다. 당연하게도 Spring 3.x Version 부터는 자바 17 이상 버전을 사용함으로써 javax 에서 jakarta 를 사용하는 springdoc 을 사용해야 하지만 Spring 2.x Version 에서는 자바 17 미만 버전을 사용하고 javax 에 맞춘 springfox 를 사용하셔야 합니다.

 

Swagger 커스터마이징

Swagger 에서는 기본 제공해주는 UI 말고도 추가적인 설명이나, 보충해줄 수 있는 UI 들을 개발자가 설정하고 확인하실 수 있습니다.

메인 커스텀

 

그림에서 보는바와 같이 설정을 하고 싶다면 아래 코드처럼 만들어 주시면 됩니다.

 

@OpenAPIDefinition(
  info = @Info(title = "Chan Restful Service API 명세서",
               description = "Swagger 을 이용한 API 명세서 입니다.",
               version = "v1.0.0"))
@Configuration
public class SwaggerConfig {
  
  @Bean
  public GroupedOpenApi customTestOpenApi() {
    
    String[] paths = {"/user/**", "/filter/**"};
    
    return GroupedOpenApi
      .builder()
      .group("일반 사용자와 관리자를 위한 User 도메인에 대한 API 입니다.")
      .pathsToMatch(paths)
      .build();
  }
}

 

paths 에서 user, filter 경로 하위에 URL 에 해당하는 부분은 전부 적용한다는 의미입니다.

즉, /user/id 이거나 /filter/user 등에 해당하는 경로는 "일반 사용자와 관리자를 위한 User 도메인에 대한 API 입니다" 라는 title 을 갖게됩니다. 

@OpenAPIDefinition 에 해당하는 설명들은 그림에서 보시는 바와 같이 최상단에서 사용자들에게 설명해주는 타이틀정보나 버전정보들을 설정하는 부분입니다.

 

객체정보 커스텀

@Data
@AllArgsConstructor
@Schema(description = "사용자 상세 정보를 위한 도메인 객체")
public class User {

  @Schema(title = "사용자 ID", description = "사용자 ID 는 자동생성 입니다.")
  private int id;
  
  @Schema(title = "사용자 이름", description = "사용자 이름은 2글자 이상 입력해주세요.")
  @Size(min = 2, message = "{Min.user.username}")
  private String name;
  
  @Schema(title = "등록일", description = "사용자의 등록일입니다.")
  @Past(message = "{Past.user.date}")
  private Date myDate;
}

 

위와 같이 객체에 대한 추가적인 설명이나 타이틀이 필요한 경우 @Schema 어노테이션을 사용하시면

손쉽게 설명을 추가하실 수 있습니다.

 

컨트롤러 커스텀

 

 

 

@RestController
@RequiredArgsConstructor
@Tag(name = "UserController", description = "UserController 입니다.")
public class UserController {
  
  private final UserService userService;
  
  @Operation(summary = "모든 사용자 찾기", description = "모든 사용자를 찾습니다.")
  @GetMapping("/users")
  public List<User> findAllUser() {
    return userService.findAll();
  }
  
  @Operation(summary = "특정 사용자 찾기", description = "특정 사용자를 찾습니다.")
  @ApiResponses(value = {
    @ApiResponse(responseCode = "200",
                 description = "유저찾기성공",
                 content = {@Content(mediaType = "application/json",
                                     schema = @Schema(implementation = ApiResponse.class))}),
    @ApiResponse(responseCode = "400",
                 description = "잘못된 요청입니다.",
                 content = @Content)
  })
  
  @GetMapping("/user/{id}")
  public User findUser(
   @Paramter(description = "사용자ID", required = true, example = "1")
   @PathVariable int id) {
   
     if(userService.findOne(id) == null) {
       throw new NotFoundUserException("유저를 찾을 수 없습니다.");
     }
     
     // ...
  }
  
}

 

위와 같이 @Tag, @ApiResponse, @Operation 등을 이용해서 Controller 부분도 다양하게 커스텀 할 수 있습니다.