계기

기존에는 Redis를 이용해서 pub/sub 방식으로만 관리 도구를 이용하였는데,
운영에 용이하도록 백오피스를 구축하고 싶어서 Controller를 만들면서 Swagger를 붙이기로 했다.

Swagger 적용하는 방법

1. build.gradle에 dependency 추가

springdoc-openapi v2.2.0 - 2. Getting Started

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
}

2. Swagger 접속하기

• 설정을 변경했을 경우
  http://(server):(port)/(context-path)/index.html
• 기본 설정일 경우
  http://localhost:8080/swagger-ui/index.html
  

페이지에 접속하면 기본 Swagger UI를 확인할 수 있다.

커스터마이징 하기

Swagger에서 API 이름과 버전 변경

1. config pakage 생성 후, SwaggerConfig.java 파일 생성
2. @OpenAPIDefinition(info = @Info(title = "원하는 API Docs 이름", description = "API 설명", version = "버전")) 어노테이션을 추가해준다.

package com.xxx.xxx.config;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(info = @Info(title = "Keyword Management Tool API", description = "키워드 관리를 위한 API 목록입니다.", version = "1.0"))
@Configuration
@RequiredArgsConstructor
public class SwaggerConfig {
    
}

완성

Controller 설명 추가

• 설명을 추가하고 싶은 컨트롤러 파일 안에 @Tag(name = "컨트롤러 이름", description = "컨트롤러 설명")을 추가한다.

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "Controller", description = "테스트를 위한 빌드 검증 컨트롤러")
@RestController
@RequestMapping("/test")
public class Controller {
    @GetMapping
    public String getTest() {
        return "Success";
    }
}

완성

각 API에 대한 설명 추가

• 추가하고 싶은 API에 @Operation(summary = "API 역할에 대한 요약", description = "API가 수행할 역할에 대한 자세한 설명")

    @Operation(summary = "신규 키워드 리스트 조회", description = "신규로 키워드 검색량을 수집할 키워드와 등록 날짜를 포함한 키워드 리스트 결과를 조회합니다.")
    @GetMapping(value = "/new")
    public Page<NewKeyword> getNewwords(@RequestParam(name = "page", defaultValue = "0") int page,
                                        @RequestParam(name = "size", defaultValue = "10") int size) {
        Pageable pageable = PageRequest.of(page, size);
        return newWordRepository.findAllByOrderByKeyword(pageable);
    }

완성

끝

References

• Chat GPT
• springdoc-openapi