[Spring] Swagger

Swagger

Swagger란 개발한 REST API를 편리하게 문서화해주고, 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트이다.
Spring Boot에서는 간단하게 gradle dependencies를 추가 함으로 사용이 가능하다.

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.
Swagger

Swagger 기본 설정

📌dependency 추가

implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

📌application.properties 추가

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

📌Configuration 추가

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

👉http://localhost:8080/swagger-ui.html#/로 접속하면 API 문서 확인이 가능하다.

Swagger UI 편집하기

📌문서 상단 내용 설정하기

@Configuration
@EnableSwagger2
public class SwaggerConfig {

   @Bean
   public Docket api() {

       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(swaggerInfo())
               .groupName("Test")
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.crypto.admin"))
               .paths(PathSelectors.ant("/**"))
               .build()
               .useDefaultResponseMessages(false);
   }

   private ApiInfo swaggerInfo() {
       return new ApiInfoBuilder().title("Test API Documentation")
               .description("Swagger UI 간단 예제입니다.")
               .license("라이센스소유자")
               .licenseUrl("라이센스URL")
               .version("1.0")
               .build();
   }
}

결과

📌Controller 설정하기

@Api(tags = {"사용자 로그인 서비스"}, description = "사용자 로그인 관련 서비스")
@Controller

결과

📌Controller내의 Method 설정하기

@PostMapping("/login")
    @ApiOperation(value = "사용자별 인증 정보 CHECK", notes = "인증된 사용자인지 판단하는 API입니다.")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "email", value = "사용자 식별 이메일", required = true),
            @ApiImplicitParam(name = "password", value = "사용자 비밀번호", required = true)
    })
    public String login( Member member, @ApiIgnore HttpSession session){}

✔@ApiOperation : 해당 메서드 수행 서비스에 대해 상세 설명한다.

✔@ApiImplicitParams : 해당 메서드에 필수적인 인자 값에 대해 설명한다.

✔@ApiIgnore : HttpSession에 대해 정보를 숨긴다.

결과

📌마무리

❗의문점
해당 메서드는 Member DTO를 받기 때문에 Member의 변수들이 모두 출력되고 필요한 인자인 email과 password에 대해 required로 표시되어 있다.
나는 다른 변수들의 정보를 숨기고 싶어서 인자는 Member에 @ApiIgnore을 사용하여 출력해보았지만 이 경우 로그인 기능이 제대로 수행되지 않음을 확인하였다.
따라서 DTO 모델을 인자로 받을 때 필요 인자 정보만 출력하는 방안에 대해 고민해볼 필요가 있음을 알게 되었다.

❗Check Point
Method를 설정함에 있어 @ApiImplicitParams을 작성할 때 어떤 인자에 대한 정보를 제공해야 하는지 의문이 들었다.
로그인한 사용자가 결제를 통해 포인트를 충전하면 Session 값에 있는 email값으로 해당 유저의 데이터 베이스에 데이터를 저장하게 된다. 그렇다면 @ApiImplicitParam으로 email을 명시해야 할 필요가 있을까?
결론부터 말하자면 그럴 필요가 없다.
Swagger API내에서도 해당 메서드를 수행하는 기능이 있다.
Try it out을 통해 메서드를 수행할 수 있는데 email값의 명시가 없더라도 로그인이 되어 있지 않다면 AOP에 의해 로그인 수행을 출력할 것이고, 로그인이 되어 있는 사용자라면 해당 메서드가 성공적으로 수행될 것이다.