[spring] swagger 사용법

이민재·2022년 10월 2일

하던 프로젝트 스웨거 정리

1. swagger 설정 추가

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket restAPI() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("ohgwang.demori"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("대모리")
                .description("대모리's Swagger")
                .version("0.0.1")
                .build();
    }
}

swagger 설정 코드

ApiInfo apiInfo()
API 이름과 현재 버전 등 해당 API 정도 기입

ParameterBuilder
API를 테스트할때 모든 API에 전역 파라미터를 설정한다.
해당소스는 모든 API 테스트시 header에 'Autorization' 이라는 값을 추가하도록 했다.

Parameter parameterBuilder = new ParameterBuilder()
           .name(HttpHeaders.AUTHORIZATION)
           .description("Access Tocken")
           .modelRef(new ModelRef("string"))
           .parameterType("header")
           .required(false)
           .build();

적용 후에 header 가 추가 된것을 확인

RequestHandlerSelectors.basePackage(String packageName)

Swagger를 적용할 클래스의 package 명을 적어준다.

PathSelectors.any()

해당 package 하위에 있는 모든 url에 적용시킨다. /test/**로시작되는 부분만 적용해주고싶다면
PathSelectors.ant(String pattern) 메서드에 url parttern을 추가해주면된다.

변경된 swaggerconfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {

   @Bean
   public Docket restAPI() {
       Parameter parameterBuilder = new ParameterBuilder()
               .name(HttpHeaders.AUTHORIZATION)
               .description("Access Tocken")
               .modelRef(new ModelRef("string"))
               .parameterType("header")
               .required(false)
               .build();

       List<Parameter> globalParamters = new ArrayList<>();
       globalParamters.add(parameterBuilder);

       return new Docket(DocumentationType.SWAGGER_2)
               .globalOperationParameters(globalParamters)
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.basePackage("ohgwang.demori"))
               .paths(PathSelectors.any())
               .build();
   }

   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("대모리")
               .description("대모리's Swagger")
               .version("0.0.1")
               .build();
   }
}

2. swagger 어노테이션

@Api(value="~", tags="~"): 해당 클래스가 Swagger 리소스임을 명시
value: 사용자 지정 이름 기재, tags사용 시, 무시되게 된다.
tags: 태그에 여러 이름을 콤마(,) 단위로 기재 시, 여러 태그 정의 가능
@ApiOperation(value="~", notes="~"): 해당 api에 대한 명세
value: 현재 api에 대한 정의
notes: 현재 api에 대한 Comment
@ApiParam(value="~", required="~", example="~"): 파라미터에 대한 명세
value: 현재 파라미터에 대한 설명
required: 필수 여부
example: 파라미터 예시
@ApiModelProperty(value="~", required="~", example="~") : 객체 필드에 대한 설명

3. 예시

 @PatchMapping()
    @ApiOperation(value = "유저 권한 변경")
    @ApiResponses({
            @ApiResponse(code = 200, message = "성공"),
            @ApiResponse(code = 500, message = "서버 오류")
    })
    public ResponseEntity<? extends BaseResponseBody> changeRole(@ApiParam(value = "유저 PK")@RequestParam int userPk, @ApiParam(value = "유저 권한(0 == 일반 유저, 1 == 인증 유저 , 2 == 중지 유저)")@RequestParam int role) {

        try{
            User user = userService.findByPk(userPk);

            if(user == null){
                return ResponseEntity.status(400).body(BaseResponseBody.of(400, "없는 유저"));
            }else{
                String message = userService.changeRole(user , role);
                if("권한없음".equals(message)){
                    return ResponseEntity.status(400).body(BaseResponseBody.of(400, message));
                }
                return ResponseEntity.status(200).body(BaseResponseBody.of(200, message));
            }
        }catch (Exception e){
            return ResponseEntity.status(500).body(BaseResponseBody.of(500, "서버 오류"));
        }

    }

@Api(value = "admin API" , tags = {"admin"})
```
* tags 작성시에 value 는 무시된다.
```
@ApiOperation(value = "유저 권한 변경")
@ApiParam(value = "유저 PK")@RequestParam int userPk
- @ApiParam(value = "유저 PK",example = "1")@RequestParam int userPk
  - example 설정 시에 try시 값이 적용되어있음

@ApiOperation(value = "유저 권한 변경",response = UserAdminRes.class)

@GetMapping()
   @ApiOperation(value = "유저 리스트")
   @ApiResponses({
           @ApiResponse(code = 200, message = "성공"),
           @ApiResponse(code = 500, message = "서버 오류")
   })
   public ResponseEntity<? extends BaseResponseBody> getUsers() {
       List<User> list = null;
       try {
           list = userService.findAllUser();
           if(list == null){
               return ResponseEntity.status(400).body(BaseResponseBody.of(400, "잘못된 요청입니다"));
           }else if(list.size() == 0){
               return ResponseEntity.status(204).body(UserAdminRes.of(204,"유저가 없습니다" ,list));
           }else{
               return ResponseEntity.status(200).body(UserAdminRes.of(200,"유저 리스트" ,list));
           }

       }catch (Exception e){
           return ResponseEntity.status(500).body(BaseResponseBody.of(500, "서버 오류"));
       }
   }
``