[Spring-Boot] Srpingdoc OpenApi 스웨거(Swagger) 사용하기

 

 

Springdoc의 스웨거(Swaager)를 사용해 보자

 

 

들어가며

팀 프로젝트를 진행하면서 API 문서를 작성하기 위해 노션을 사용했었지만, 직접 작성하는 과정에서 불편함을 느꼈습니다. 또한, 프런트엔드 개발자로서 API가 올바르게 작동하는지 확인하는 과정에서도 어려움을 겪었습니다. 이런 어려움을 해결하기 위해 Swagger를 사용하여 API 명세서를 작성하게 되었습니다.

---

 

Springdoc-openAPI 스웨거란?

Spring 프레임워크 기반의 RestFul API를 문서화하기 위한 Open API입니다.

 

그리고 스프링 구성, 클래스 구조 및 다양한 주석을 기반으로 API 의미를 추론하기 위해 런타임에 애플리케이션을 검사하는 방식으로 작동합니다.

 

JSON/YAML 및 HTML 형식 API로 문서를 자동으로 생성하여 개발자가 직접 API명세를 작성할 시간을 줄여주는 아주 좋은 녀석입니다..(직접 노션에 작성하는 시간이 너무 아까웠습니다...)

 

지원하는 기능

OpenAPI 3

Spring Boot v3 (Java 17 및 Jakarta EE 9)

JSR-303, 특히 @NotNull, @Min, @Max 및 @Size.

Swagger UI

OAuth 2

GraalVM 네이티브 이미지

 

위와 같은 여러 기능을 지원하고 있다.

 

여러 종류의 Swagger-API

스웨거는 크게 Springfox , Springdoc 두 가지 버전으로 구분된다. 하지만. 기존에 먼저 나왔던 Springfox 라이브러리가 종료를 하게 되어 SrpingBoot 3.x.x이상 버전을 사용하게 되면 더 이상 사용할 수 없게 되었다. 

---

 

 

Springdoc-openAPI Swagger 사용하기

의존성 추가하기

Gradle

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

 

Application.yml

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    groups-order: DESC
    operationsSorter: method
    disable-swagger-default-url: true
    display-request-duration: true
  api-docs:
    path: /api-docs
  show-actuator: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  paths-to-match:
    - /api/**

• swagger-ui: Swagger UI 설정을 정의합니다.
  • path: Swagger UI에 접근할 수 있는 경로로 일반적으로 /swagger-ui.html와 같은 경로를 사용합니다..
  • groups-order: API 그룹을 표시하며 DESC(내림차순)으로 설정.
  • operationsSorter: API 작업을 표시하는 방법으로 메서드에 따라 정렬.
  • disable-swagger-default-url: 기본 Swagger URL 사용을 비활성화합니다.
  • display-request-duration: 요청 지속 시간을 표시 여부를 설정
• api-docs path: API 명세서에 접근할 수 있는 경로
• show-actuator: Actuator Endpoints를 표시할지 여부 설정.
• default-consumes-media-type: 기본 요청 미디어 유형을 설정
• default-produces-media-type: 기본 응답 미디어 유형을 설정
• paths-to-match: 해당 문서를 보이기 위한 경로를 설정한다.

 

SwaggerConfig

@OpenAPIDefinition(
        info = @Info(title = "코드 기록사의 API 명세서",
                description = "백엔드 API 서버",
                version = "v1")
)
@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi chatOpenApi() {
        String[] paths = {"/api/**"};

        return GroupedOpenApi.builder()
                .group("코드 기록사의 Swagger-v1")
                .pathsToMatch(paths)
                .build();
    }
}

• @OpenAPIDefinition: 이 어노테이션은 OpenAPI의 기본 정보를 설정.
  • title: API의 제목을 설정
  • description: API에 대한 설명을 설정
  • version: API의 버전을 설정
• GroupedOpenApi: 이 클래스는 Swagger 그룹을 정의하고 해당 그룹에 대한 OpenAPI 설정을 구성.
  • group: Swagger 그룹의 이름을 설정.
  • pathsToMatch: 그룹에 속하는 API 엔드포인트의 경로 패턴을 지정

 

 

SwaggerController

@RestController
@Tag(name = "사용자 API",description = "사용자의 관한 API 입니다.")
@RequiredArgsConstructor
@RequestMapping("/api")
public class SwaggerController {

    private final MemberService memberService;

    @GetMapping("/{id}")
    @Operation(summary = "사용자 조회",description = "가입한 사용자의 정보를 조회합니다.")
    public ResponseEntity<?> getMember(@PathVariable("id") Long id){
        memberService.getMembers(id);
        return ResponseEntity.status(HttpStatus.CREATED).body("조회 성공");
    }

    @PostMapping("/save")
    @Operation(summary = "사용자 저장",description = "사용자가 해당 API에 가입합니다..")
    public ResponseEntity<?> saveMember(@RequestBody MemberDto memberDto){
        memberService.save(memberDto);
        return ResponseEntity.status(HttpStatus.CREATED).body("가입 성공");
    }

    @PutMapping("/{id}")
    @Operation(summary = "사용자 이름 수정",description = "가입한 사용자의 이름을 변경합니다.")
    public ResponseEntity<?> updateMember(@PathVariable("id") Long id,@RequestBody UserRequest request){
        memberService.updateMember(id,request.getUsername());
        return ResponseEntity.status(HttpStatus.CREATED).body("업데이트 성공");
    }


    @DeleteMapping("/{id}")
    @Operation(summary = "사용자 탈퇴",description = "가입한 사용자가 탈퇴 합니다.")
    public ResponseEntity<?> deleteMember(@PathVariable("id") Long id){
        memberService.deleteMember(id);
        return ResponseEntity.status(HttpStatus.CREATED).body("삭제 성공");
    }
}

 

위와 같이  간단한 사용자 관련  GET, POST, DELETE, PUT API를 구현했다고 해보자

 

"http://localhost:8080/swagger-ui/index.html"

 접속하면 다음과 같이 우리가 설정한 API 문서가 생성되어 나오는 것을 확인할 수 있을 것이다.

 

 

 

 

저장 API를 스웨거를 통해서 정상적으로 작동하는지 한번  실행해 보자

 

우리가 설정하는 201의 상태코드와 함께 가입성공이 된 것을 볼 수 있다. 

 

DB에도 정상적으로 데이터가 들어야 저장되어 있는 것을 볼 수 있다 이로써 정상적으로 문서화된 것을 볼 수 있다.

---

 

마무리

이로써 간단하게 Swagger을 통해 자동으로 문서화하는 방법을 알아보았습니다. 여기서 더욱 풍부하게 Swagger 문서를 작성할 수 반환타입 예외의 대한 예시 반환 타입을 작성하거나, 응답 데이터를 어떤식으로 데이터가 작성해야하는지 직접 작성할수 도있습니다. 이런 방식을 한번 시도해 보면 좋을 것 같습니다.

---

 

참고

• https://springdoc.org/#spring-webmvc-support

OpenAPI 3 Library for spring-boot

• https://github.com/springdoc/springdoc-openapi