Swagger, Springdocs

오늘은 Swagger와 Springdocs에 대해서 간단하게 알아보고 사용해보자.

그게 뭔데?

 

Swagger란 쉽게 말해서 API 문서 작업을 대신 해주는 것이라고 보면 된다.

Swagger UI를 통해 문서화된 API를 시각적으로 확인하고 테스트 할 수 있다.

 

엄청 신기하다.

 

그럼 Springdocs는???

 

쉽게 말하면 Swagger를 Spring Boot에서 더 쉽게 사용할 수 있도록 해주는 친구이다.

API 문서를 간편하게 작성할 수 있도록 돕고 문서화된 API를 Swagger UI를 통해 시각적으로 볼 수 있게 해준다.

 

그럼 이제 사용해보자.

 

일단 gradle에 의존성 설정을 해준다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

 

 

그리고 yml에 기본 설정을 해준다.

 

 

이까지 설정을 마쳤으면 Swagger 설정을 해줄 클래스를 만들어야한다.

 

// 문서의 기본 정보를 정의
@OpenAPIDefinition(
        info = @Info(title = "회원가입 API 명세서",
                description = "결혼 어플 서비스 API 명세서",
                version = "v1"))
@RequiredArgsConstructor
@Configuration // 이 클래스가 Spring 설정 파일임을 나타냄
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi groupedOpenApi() {
        String[] paths = {"/v1/**"};

        // 그룹화된 OpenAPI 객체 생성 후 반환
        return GroupedOpenApi.builder()
                .group("회원가입 API v1") // 그룹 이름 설정
                .pathsToMatch(paths) // paths 에서 적은 패턴으로 매칭
                .build();
    }
}

 

 

이 클래스까지 완성했다면 Controller에 적용해주자

 

public class MemberController {
    private final MemberService memberService;

    @Operation(summary = "회원 둥록", description = "회원 정보가 등록됩니다.", tags = { "Member Controller" })
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "OK",
                    content = @Content(schema = @Schema(implementation = Member.class))),
            @ApiResponse(responseCode = "400", description = "BAD REQUEST"),
            @ApiResponse(responseCode = "404", description = "NOT FOUND"),
            @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR")
    })
    @PostMapping("v1/members")
    public Member register(@RequestBody MemberCreateRequest request) {
        return memberService.create(request);
    }

    @Operation(summary = "회원 조회", description = "회원 정보를 조회합니다.", tags = {"Member Controller"})
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "OK",
                    content = @Content(schema = @Schema(implementation = Member.class))), // 응답 성공했을때 OK라는 description이 뜨고 Member 클래스로 응답한다, 스키마란? 데이터의 구조 형식 제약 조건등을 정의하는 명세서
            @ApiResponse(responseCode = "400", description = "BAD REQUEST"),
            @ApiResponse(responseCode = "404", description = "NOT FOUND"),
            @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR")
    })
    @GetMapping("v1/members/{memberNo}")
    public Member getMember(@PathVariable("memberNo") Long memberNo) {
        return memberService.getMember(memberNo);
    }
}

 

 

뭐가 되게 복잡하다.

하나하나 결과를 보면서 비교해보자

 

일단 앱을 실행한 뒤 아까 우리가 설정한 주소로 접속을하면

 

이런 창이 뜰 것이다.

 

Controller에서 적용해준 부분이 나타난 것을 볼 수 있다.

 

처음 기본 정보들을 등록한 부분

 

 

 

제목과, 버전, 내용이 적용되어 나온 것 볼 수 있다.

 

 

에러와 성공할때 나올 내용을 정의해놨다.

 

 

 

이런 식으로 테스트를 하며 설정한 대로 결과를 확인할 수 있다.

 

 

아직 깊게 이해하지 못해 모든 기능을 다 써보진 못한 것 같지만

api 문서화를 자동으로 하고 시각적으로 보여주게 까지는 한 것 같아 유익한 시간이였다.