[Spring Boot Tutorial] 15. Open API 3.0 + Swagger v3 상세설정

1. api 그룹 설정 : @Tag
2. api Schema 설정 : @Schema
3. api 상세 정보 설정 : @Operation
4. api response 설정 : @ApiResponse
5. api parameter 설정 : @Parameter

---

이전시간에 OpenAPI info 정보만 설정했었습니다.

Schemas 에 대한 설명과 들어갈 값에대한 정보도 없고, api method에 대한 설명도 없어서 api 이용에 불편함이 있습니다.

이번시간에는 Swagger v3 Annotation을 이용하여 API 문서의 설명을 구체적으로 작성하고, Java Bean Validation 을 이용하여 api 사용시 유효성 체크를 합니다.

---

1. api 그룹 설정 : @Tag

Target : ANNOTATION_TYPE, METHOD, TYPE

• name : 태그의 이름
• description : 태그에 대한 설명

Tag에 설정된 name이 같은 것 끼리 하나의 api 그룹으로 묶습니다.
주로 Controller Class 나 Controller Method 영역에 설정합니다.

import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "user", description = "사용자 API")
@RequestMapping(value = "${demo.api}/users")
@RestController
public class UserController {
  ...
}

UserController 에 @Tag를 설정해 보았습니다.

@Tag 애너테이션 설정을 완료한 후 Swagger UI 화면입니다.
태그명과 설명이 각 태그에 설정되었습니다.

---

2. api Schema 설정 : @Schema

Target : ANNOTATION_TYPE, FIELD, METHOD, PARAMETER, TYPE

• description : 한글명
• defaultValue : 기본값
• allowableValues :

Schmea(= Model)에 대한 정보를 작성하는 곳입니다.
Schema를 설정할 시, 더욱 완성도 높은 Swagger UI 문서를 만들 수 있습니다.

@Schema 설정을 하지 않은 UserValue 모델 정보입니다.
각 필드값들에대한 설명이나 기본값, 허용가능한 값 등에 대한 정보 없이 string 요소가 들아간다는 말뿐이라 어떤 값이 들어가는지 모호합니다.

api 문서의 완성도를 높이기 위해서는 @Schema 설정을 통해 어떤 값들이 들어가는지 설정을 추가해주는 것이 좋습니다.

@Schema(description = "사용자")
@Getter @Setter
public class UserValue {

	@Pattern(regexp = "[0-2]")
	@Schema(description = "유형", defaultValue = "0", allowableValues = {"0", "1", "2"})
	private String type;

	@Email
	@Schema(description = "이메일", nullable = false, example = "abc@jiniworld.me")
	private String email;

	@Schema(description = "이름")
	private String name;

	@Pattern(regexp = "[1-2]")
	@Schema(description = "성별", defaultValue = "1", allowableValues = {"1", "2"})
	private String sex;

	@DateTimeFormat(pattern = "yyMMdd")
	@Schema(description = "생년월일", example = "yyMMdd", maxLength = 6)
	private String birthDate;

	@Schema(description = "전화번호")
	private String phoneNumber;

	@Schema(description = "비밀번호")
	private String password;

}

Model 클래스에 대한 한글명을 설정할 수도 있고 (ln 1)
각 필드값에 대한 설정도 할 수 있습니다.
description에 한글명을 작성하고, defaultValue를 통해 기본값을 제공할 수 있습니다.
allowableValues 설정을 하면 Schema 정보에서 리스트 형태로 들어갈 수 있는 데이터 정보를 볼 수 있습니다.

만일, Validation 체크를 하고 싶다면 javax.validation.constraints 패키지를 이용하면 됩니다.
특정 Regex를 이용하여 패턴체크를 하고 싶다면 Pattern을 이용하면 됩니다.

@Schema 적용을 마친 후의 UserValue 모델 정보입니다.

---

3. api 상세 정보 설정 : @Operation

Target : ANNOTATION_TYPE, METHOD

• summary : api에 대한 간략 설명
• description : api에 대한 상세 설명
• responses : api Response 리스트
• parameters : api 파라미터 리스트

애너테이션으로 api 동작에 대한 명세를 작성하는 애너테이션으로, Controller method에 설정합니다.

Swagger UI가 fold상태일때도 간략히 확인할 수 있는 간략정보는 summary에 작성하고, 필요에 따라 상세 정보를 표기하고자 한다면 description에 설명을 추가하면 됩니다.

responses는 아래에서 설명할 @ApiResponse 리스트들 설정하는 요소입니다.
parameters는 path, query, header, cookie 등의 형태로 들어오는 파라미터에 대한 정보를 설정하는 요소입니다.

@GetMapping("/{id}")
@Operation(summary = "회원 조회", description = "id를 이용하여 user 레코드를 조회합니다.")
public ResponseEntity<? extends BasicResponse> select(
    @Parameter(description = "user 의 id") @PathVariable("id") long id) {
  ...
}

위의 코드는 summary와 description을 설정한 회원조회 api입니다.

@Operation 설정 후, Swagger UI에 메서드에 대한 설명글이 추가되었습니다.

---

4. api response 설정 : @ApiResponse

Target : ANNOTATION_TYPE, METHOD, TYPE

• responseCode : http 상태코드
• description : response에 대한 설명
• content : Response payload 구조
  • schema : payload에서 이용하는 Schema
    • hidden : Schema 숨김여부
    • implementation : Schema 대상 클래스

@ApiResponse 는 응답 결과에 따른 response 구조를 미리 확인할 수 있게 해줍니다.

@ApiResponse를 설정하지 않으면 Swagger UI에서는 상태코드 200과 비어있는 response body를 보여줍니다.

무늬뿐인 response 구조가 아닌, api 조회 성공 및 실패시 발생될 상태코드 및 Response 구조를 설정하고자 한다면 @ApiResponse를 설정하면 됩니다.

회원 조회 API 에 @ApiResponse 애너테이션을 추가해봅시다.

demo 애플리케이션의 회원 조회 API에서는 200, 404 상태코드가 설정되어 있습니다.
조회가 성공되었을 시, 200 상태코드와 CommonResponse<User> reseponseBody가 반환되고
조회 실패시엔, 404 상태코드와 ErrorResponse responseBody가 반환됩니다.

implementation 에 responseBody로 제공될 클래스의 Class 타입을 반환해야하는데, 이때 주의해야할 점은 implementation에는 class literal 타입만 들어갈 수 있다는 점입니다.

@Schema(description = "회원 Response")
public class UserResponse extends CommonResponse<User> {
	public UserResponse(User data) {
		super(data);
	}
}

조회 성공에 대한 class literal 선언을 위해 UserResponse 클래스를 새로 생성했습니다.

@GetMapping("/{id}")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "회원 조회 성공", content = @Content(schema = @Schema(implementation = UserResponse.class))),
    @ApiResponse(responseCode = "404", description = "존재하지 않는 리소스 접근", content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@Operation(summary = "회원 조회", description = "id를 이용하여 user 레코드를 조회합니다.")
public ResponseEntity<? extends BasicResponse> select(
    @PathVariable("id") long id) {
  ...
}

@ApiResponse 리스트는 @ApiResponses 에 담아 api method에 설정해도 되고,

@GetMapping("/{id}")
@Operation(summary = "회원 조회", description = "id를 이용하여 user 레코드를 조회합니다.", responses = {
    @ApiResponse(responseCode = "200", description = "회원 조회 성공", content = @Content(schema = @Schema(implementation = UserResponse.class))),
    @ApiResponse(responseCode = "404", description = "존재하지 않는 리소스 접근", content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
public ResponseEntity<? extends BasicResponse> select(
    @PathVariable("id") long id) {
  ...
}

@Operation의 responses 요소에 설정해도 됩니다.

@ApiResponse 를 적용한 후의 Swagger UI 화면입니다.

---

5. api parameter 설정 : @Parameter

Target : ANNOTATION_TYPE, FIELD, METHOD, PARAMETER

• name : 파라미터 이름
• description : 파라미터 설명
• in : 파라미터 위치
  • query, header, path, cookie

@ApiResponse 와 마찬가지로 @Parameters 애너테이션에 @Parameter 리스트를 담아 api 메서드에 설정할 수 있고, @Operation 애너테이션의 parameters 요소에 설정할 수 있습니다.

그리고, 파라미터의 경우, api method의 인자값에 붙여 명시적으로 설정할 수도 있습니다.

@Parameters 나 @Operation에 설정하는 방법은 @ApiResponse에서와 유사하므로, 이번에는 method 인자값에 붙이는 방법을 예제로 설명하겠습니다.

@GetMapping("/{id}")
@Operation(summary = "회원 조회", description = "id를 이용하여 user 레코드를 조회합니다.", responses = {
    @ApiResponse(responseCode = "200", description = "회원 조회 성공", content = @Content(schema = @Schema(implementation = UserResponse.class))),
    @ApiResponse(responseCode = "404", description = "존재하지 않는 리소스 접근", content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
public ResponseEntity<? extends BasicResponse> select(
      @Parameter(name = "id", description = "user 의 id", in = ParameterIn.PATH) @PathVariable("id") long id) {
  ...
}

path로부터 들어올 파라미터인 id에 대한 설정을 추가했습니다.
@PathVariable 설정 앞에 @Parameter 애너테이션 설정을 추가했는데, 메서드의 인자앞에 직접 설정할 경우에는 name을 생략할 수 있습니다.

만일 @Parameters 나 @Operations에 파라미터를 설정할 경우에는 어떤 파라미터에 대한 설정인지 알수 없기 때문에 반드시 name을 설정해 줘야 합니다.

Swagger v3 애너테이션 적용을 마친 후의 Swagger UI 화면입니다.

---

※ GitHub에서 demo 프로젝트를 다운받아 볼 수 있습니다.