Springdoc을 이용한 swagger3 구현

1.build.gradle

implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'

2.application.properties

springdoc.swagger-ui.path=/swagger-ui.html
#swagger 접속 주소 ex) localhost:8080/swagger-ui.html
springdoc.swagger-ui.groups-order=asc
#swagger group 정렬 순서 desc,asc
springdoc.swagger-ui.operations-sorter=
# method순으로 정렬

Reference

https://springdoc.org/properties.html

Springdoc-openapi Properties

3.annotation

(1) api 그룹 설정:@Tag

@Tag(name = "member",description = "사용자 API")
public class MemberController {
...
}

@Tag 적용 swagger ui

name:그룹 이름

description:그룹 설명

 

@Tag에 설정된 name이 같은 것끼리  하나의 api그룹이 생성됩니다.

(2) api Schema 설정 : @Schema

@Getter
@NoArgsConstructor
public class MemberSaveDto {

    @NotBlank(message = "이름을 입력해주세요")
    @Schema(description = "유저이름")
    private String name;

}

@Schema description 미 적용시 swaager ui

@Schema description 적용시 swagger ui

각 필드에 여러가지 설명을 붙일 수 있습니다.

description:각 필드의 설명

defaultValue:기본 값

allowValues:허용 값  ex) {1,2}

minlength:최소 길이

maxlength:최대 길이

hidden:필드 숨기기 

등 많은 옵션을 제공합니다.

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

@GetMapping("/members/{memberId}")
@Operation(summary = "회원 찾기" , description = "회원의 id을 받아 회원을 찾습니다.")
public ResponseEntity<Member> findMember(@PathVariable Long memberId){
        return new ResponseEntity<>(memberService.findMember(memberId), HttpStatus.CREATED);
 }

@Operation 적용 swagger ui

summary: api에 대한 간략 설명

description : api에 대한 상세 설명

responses : api Response 리스트

parameters : api 파라미터 리스트

4. api response 설정 : @ApiResponse

@GetMapping("/members/{memberId}")
    @Operation(summary = "회원 찾기" , description = "회원의 id을 받아 회원을 찾습니다.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200",description = "회원 찾기 성공",content = @Content(schema = @Schema(implementation = Member.class))),
            @ApiResponse(responseCode = "400_1",description = "올바르지 않은 회원 id",content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
    })
    public ResponseEntity<Member> findMember(@PathVariable Long memberId){
        return new ResponseEntity<>(memberService.findMember(memberId), HttpStatus.CREATED);
    }

@Api response 적용시 swagger ui

responseCode : http 상태코드

description : response에 대한 설명

content : Response payload 구조

schema : payload에서 이용하는 Schema

hidden : Schema 숨김여부

implementation : Schema 대상 클래스

 

@ApiResponse 어노테이션을 이용하면 api 성공 및 실패시 response에대한 상태 코드및 설명 ,response 구조를 설정 할 수 있습니다. response 코드가 같을시 한가지의 경우만 나오므로 구분자(ex)_1,_2)를 이용하여 구분해주어야 합니다.