[spring] swagger 사용법

이민재·2022년 10월 2일
0

하던 프로젝트 스웨거 정리

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 어노테이션

  1. @Api(value="~", tags="~"): 해당 클래스가 Swagger 리소스임을 명시
    value: 사용자 지정 이름 기재, tags사용 시, 무시되게 된다.
    tags: 태그에 여러 이름을 콤마(,) 단위로 기재 시, 여러 태그 정의 가능
  2. @ApiOperation(value="~", notes="~"): 해당 api에 대한 명세
    value: 현재 api에 대한 정의
    notes: 현재 api에 대한 Comment
  3. @ApiParam(value="~", required="~", example="~"): 파라미터에 대한 명세
    value: 현재 파라미터에 대한 설명
    required: 필수 여부
    example: 파라미터 예시
  4. @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, "서버 오류"));
           }
       }
    ``

코드에서는 리턴 값이 ResponseEntity<? extends BaseResponseBody>로 설정 되어 있다.
성공 할때는 UserAdminRes값을 리턴 받는다.

하지만 표기 되는건 BaseResponseBody가 표기 된다.
이 때 @ApiOperation(value = "유저 권한 변경",response = UserAdminRes.class)
response = UserAdminRes.class 를 표기 해주면 변경된다.


저번 프로젝트 진행 중에는 스웨거 적용을 안하고 진행하다가 마지막에 하나하나 손으로 api를 정리하다가 다음 프로젝트에서는 스웨거를 써야겠다라고 눈물을 흘리며 다짐했는데

결국 이번 프로젝트에서는 예쁘게 정리하는 법을 너무 늦게 알아서 눈물을 흘리는 중입니다.

다음 프로젝트에서는 만들때 하나하나 생각하면서 작성 하도록 노력할 생각입니다.

profile
초보 개발자

0개의 댓글