Swagger [2] Annotation (1)

Swagger Annotation (2) ← 본문 링크

Swagger Annotation (3) ← 작성 예정

이전 포스팅에서 Swagger의 기본 개념 및 JAVA Spring Boot 환경에 사용하는 방법에 대하여 알아보았다. 이번에는 Annotation에 대하여 알아보고자 한다. Swagger Annotation을 이용하여 API 명세 화면(swagger-ui.html)을 보다 쉽게 Control 할 수 있다.

Swagger Annotation(간략)

@ApiIgnore
- class에 붙여 사용하는 Annotation
- ui 화면에서 보이지 않도록 ignore 설정을 가능케한다.
@Api
- class에 붙여 사용하는 Annotation
- ui 화면에 보이는 class 설명을 custom 할 수 있다.
@ApiOperation
- class 내 method에 붙여 사용하는 Annotation
- ui 화면에 보이는 method 설명 및 상세 사항을 설정할 수 있다.
@ApiImplicitParam
- class 내 method에 붙여 사용하는 Annotation
- ui 화면에 보이는 method parameter 설명을 설정할 수 있다.
@ApiImplicitParams
- class 내 method에 붙여 사용하는 Annotation
- 여러개의 @ApiImplicitParam Annotation을 사용할 때 사용한다.
@ApiResponse
- class 내 method에 붙여 사용하는 Annotation
- 각 method에 대한 응답 코드의 결과를 작성할 수 있다.
@ApiResponses
- class 내 method에 붙여 사용하는 Annotation
- 여러개의 @ApiResponse Annotation을 사용할 때 사용한다.

실제 Controller에 사용할 수 있는 Annotation 목록에 대하여 간략하게 정리해보았다. @ApiImplicitParam Annotation의 경우, return data로 DTO나 VO를 할 경우, 굳이 설정을 할 필요는 없다. DTO 및 VO 내 객체에 대하여 각각의 설정이 가능하기 때문인데, 필자는 주로 JSONObject를 return 하는 까닭에, 일일이 @ApiImplicitParam 및 @ApiImplicitParams Annotation을 사용하여 parameter를 명시해주었다.

Annotation 사용을 위한 준비

간단하게 Rest Controller 역할을 맡게 될 test class을 생성하고, 그 안에 test method들을 생성해보겠다.

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping(value = "/api/swagger/test")
public class SwaggerTestRestController {
  
  @GetMapping
  public String SwaggerTestMethod_1() {
    String returnData = "";
    return returnData;
  }
  
  @PostMapping
  public String SwaggerTestMethod_2() {
    String returnData = "";
    return returnData;
  }
  
  @PutMapping
  public String SwaggerTestMethod_3() {
    String returnData = "";
    return returnData;
  }
  
  @DeleteMapping
  public String SwaggerTestMethod_4() {
    String returnData = "";
    return returnData;
  }
  
}

swagger ui를 확인해보도록 하자. 다음의 이미지와 같이 새로 생성한 class 및 method가 출력되는 것을 확인할 수 있을 것이다.

Annotation - @ApiIgnore

class Annotation으로 @ApiIgnore를 적용하면, 해당 class는 swagger ui에서 출력되지 않게된다. 별도의 예제 이미지는 첨부하지 않고, 소스로 대체하도록 하겠다. ~~어차피 안보일텐데...~~

import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@ApiIgnore
@RestController
@RequestMapping(value = "/api/swagger/test")
public class SwaggerTestRestController {
  
  ... 중략 ...
  
}

Annotation - @Api

class Annotation으로 @Api를 적용하고, tags를 입력하면 swagger ui 내 출력되는 class 설명을 custom 할 수 있게된다. 예제 소스와 이미지를 참고하도록 하자. 참고로 @Api Annotation만 적용할 경우, 아무런 변화를 느낄 수 없다. tags를 입력해야만 출력되는 class 설명을 custom 할 수 있다.

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.*;

@Api(tags = "Swagger API 테스트 중입니다. ㅎㅎ")
@RestController
@RequestMapping(value = "/api/swagger/test")
public class SwaggerTestRestController {
  
  ... 중략 ...
  
}

Annotation - @ApiOperation

@ApiOperation Annotation에서는 두 가지 옵션을 사용할 수 있다. value 옵션과 notes 옵션이다. value 옵션은 swagger ui 내 method가 출력될 때, 간단하게 설명을 덧붙이는 역할을 한다. notes 옵션은 해당 method를 클릭하면, 하단에 method에 대한 설명이 dropdown 되는데, 이 때 상세 사항을 보여주도록 한다. 아래의 예제 소스 및 이미지를 참고하도록 하자.

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@Api(tags = "Swagger API 테스트 중입니다. ㅎㅎ")
@RestController
@RequestMapping(value = "/api/swagger/test")
public class SwaggerTestRestController {
  
  @ApiOperation(value = "[ GET ] 스웨거 테스트 !", notes = "Get Mapping으로, 데이터를 조회하는 용도입니다.")
  @GetMapping
  public String SwaggerTestMethod_1() {
    String returnData = "";
    return returnData;
  }
  
  @ApiOperation(value = "[ POST ] 스웨거 테스트 !", notes = "Post Mapping으로, 데이터를 수정하는 용도입니다.")
  @PostMapping
  public String SwaggerTestMethod_2() {
    String returnData = "";
    return returnData;
  }
  
  @ApiOperation(value = "[ PUT ] 스웨거 테스트 !", notes = "Put Mapping으로, 데이터를 추가하는 용도입니다.")
  @PutMapping
  public String SwaggerTestMethod_3() {
    String returnData = "";
    return returnData;
  }
  
  @ApiOperation(value = "[ DELEETE ] 스웨거 테스트 !", notes = "Delete Mapping으로, 데이터를 삭제하는 용도입니다.")
  @DeleteMapping
  public String SwaggerTestMethod_4() {
    String returnData = "";
    return returnData;
  }
  
}