[Spring] OpenAPI 3.0 Annotaion(Swagger)

학습 목표

• OpenAPI 3.0 의 어노테이션 각 기능들을 사용할 수 있다.

설치

// 주의 : Spring boot 버전이 2.x 이하여야 한다
    implementation 'org.springdoc:springdoc-openapi-ui:1.5.2'
    implementation 'org.springdoc:springdoc-openapi-data-rest:1.5.2'

1. @Tag

• 적용: Controller

• Attributes
  • name
  • description

• Example

    @Tag(name="AuthController", description ="계정관련 컨트롤러")
    public class AuthController{
        ...
    }
  

2. @Schema

• 적용: Table
• Attributes
  • description
  • dafaultValue
  • allowableValues

• Example

    @Schema(description = "회원")
    public class MemberValue {
        ... 
        @DateTimeFormat(pattern = "yy-MM-dd")
        @Schema(description = "생년월일", example = "yy-MM-dd", maxLength = 8)
        private String birthday;
  
  

3. @Operation

• 적용: Method

  • summary
  • description
  • response
  • parameters

• Example

    @GetMapping("/{email}")
    @Operation(summary = "회원 조회", description = "email 를 이용하여 member조회")
    public ResponseEntity<? extends BasicResponse> findByEmail(
        @Parameter(description = "member 의 email") @PathVariable("email") String email) {
    ...
    }
  

4. @ApiResponse

• 적용: Response type
  • responseCode : http status code
  • description
  • content : response payload
    • schema
      • hidden
      • implementation : target class

• Example

    @GetMapping("/{email}")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "회원조회 성공", content = @Content(schema = @Schema(implementation = MemberResponse.class))),
        @ApiResponse(responseCode = "404", description = "존재하지 않는 리소스", content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
    public ResponseEntity<? extends BasicResponse> findByEmail(
        @PathVariable("email") String email) {
    ...
    }
  
  

  5. @Parameter

• 적용: Parameter
  • name
  • description

  • in : 파라미터 위치

    • query
    • header
    • path
    • cookie

• Example

        @GetMapping("/member/{email}")
        public ResponseEntity<? extends BasicResponse> findByEmail(
        @Parameter(name = "email", description = "member 의 name", in = ParameterIn.PATH) @PathVariable("email") String email) {
    ...
    }