Swagger 의 api 들을 효율적으로 분리하기

기본분류

@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    @GetMapping("/xxx")
    public String xxx() {
        return "xxx";
    }
}

@RestController
@RequestMapping(value = "/student")
static class StudentController {

    @ApiOperation("학생리스트")
    @GetMapping("/list")
    public String bbb() {
        return "bbb";
    }

    @ApiOperation("특정학생의 담임목록")
    @GetMapping("/his-teachers")
    public String ccc() {
        return "ccc";
    }

    @ApiOperation("학생생성")
    @PostMapping("/aaa")
    public String aaa() {
        return "aaa";
    }
}

TAG 분류

@Api(tags = "담임관리")
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    // ...

}

@Api(tags = "학생관리")
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    // ...

}

@tag 내부 코드를 들여다 보면

때문에 아래와 같이 적용 가능하다.

@Api(tags = {"담임관리", "인사관리"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    // ...

}

@Api(tags = {"학생관리", "인사관리"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    // ...

}

좀 더 세분화 하여 분류할수 있다.

@Api(tags = {"담임관리","인사관리"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    @ApiOperation(value = "xxx")
    @GetMapping("/xxx")
    public String xxx() {
        return "xxx";
    }
}

@Api(tags = {"학생관리"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    @ApiOperation(value = "학생목록", tags = "인사목록")
    @GetMapping("/list")
    public String bbb() {
        return "bbb";
    }

    @ApiOperation("특정학생의 담임목록")
    @GetMapping("/his-teachers")
    public String ccc() {
        return "ccc";
    }

    @ApiOperation("학생생성")
    @PostMapping("/aaa")
    public String aaa() {
        return "aaa";
    }
}

분류된 그룹들을 순서 지정하기

또는 설정파일 변경

swagger.ui-config.tags-sorter=alpha

실제 코드를 보면

public enum TagsSorter {
  ALPHA("alpha");

  private final String value;

  TagsSorter(String value) {
    this.value = value;
  }

  @JsonValue
  public String getValue() {
    return value;
  }

  public static TagsSorter of(String name) {
    for (TagsSorter tagsSorter : TagsSorter.values()) {
      if (tagsSorter.value.equals(name)) {
        return tagsSorter;
      }
    }
    return null;
  }
}

코드에서 확인된 바로는 영어문자 즉 api 그룹의 영문이름을 기준으로 순서를 지정한다. 그러면 여기서 꼼수를 부리면 앞에 수자를 넣어서 하면 순서가 지정된다.

@Api(tags = {"1-담임관리", "3-인사관리"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    // ...

}

@Api(tags = {"학생관리"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    @ApiOperation(value = "학생목록", tags = "3-인사관리")
    @GetMapping("/list")
    public String bbb() {
        return "bbb";
    }

    // ...

}

API 자체에 대한 정렬

swagger.ui-config.operations-sorter=alpha

API parameter 를 정렬하기

@Data
@ApiModel(description="User Model")
public class User {

    @ApiModelProperty("user 식별자", position = 1)
    private Long id;

    @NotNull
    @Size(min = 2, max = 10)
    @ApiModelProperty("user 이름", position = 2)
    private String name;

    @NotNull
    @Max(100)
    @Min(18)
    @ApiModelProperty("user 나이", position = 3)
    private Integer age;

    @NotNull
    @Email
    @ApiModelProperty("user 메일", position = 4)
    private String email;

}

끝!