[Swagger] Spring에서 Swagger 쓰기

전현준·2024년 1월 22일

Spring

[Swagger] JavaScript에서 Swagger를 사용해보자

🍃 Spring

Swagger는 두가지의 종류가 있었습니다.

무려 3년전 이야기이지만, 아직 블로그 글이나 남아있어 말해보자면.

springfox 와 springdoc가 존재했지만 현재 Spring Boot 3.x 버전을 사용하고 있는 사람은 springfox를 사용할 수 없습니다!

~~업데이트가 2020년에 머물러 있대요.~~

Spring Boot 3.x에서는 javax.servlet를 지원하지 않아 사용할 수 없습니다.

아마 아래와 같은 오류가 발생할 것입니다.

java.lang.TypeNotPresentException: Type javax.servlet.http.HttpServletRequest not present

그럼 방법은?

springfox를 사용하려면 Spring Boot의 버전을 2.7.x로 낮춘다.
➜ Swagger 쓰겠다고 버전까지 낮춰? ~~안쓰고 말지~~

그냥 springdoc 쓴다! ✅

📝 Swagger SpringDoc 사용하기

📂build.gradle

// https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

📂application.properties

springdoc.api-docs.path=/api-docs
springdoc.packagesToScan=Your Package Name

여러 속성들은 공식 문서를 참고하자

공식 문서 : OpenAPI 3 springdoc

📂SwaggerConfig.java

Swagger 설정을 할 수 있다.

필수는 아니지만 설정해두면 아래와 같이 나온다.

설명을 첨부할 수 있다.

📝 Swagger 사용하기

📂RestResponse.java

나는 Response를 이렇게 정해두고 사용하고 있다.

Swagger 관련된 내용은 아니지만, 참고하실 분은 참고하시라.

package com.clothes.perst.DTO;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.http.HttpStatus;

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class RestResponse<T> {
    private Integer code;
    private HttpStatus httpStatus;
    private String message;
    private T data;
}

📂HomeController.java

@RestController
@RequestMapping("/member") // API의 기본 경로 설정
@Tag(name="Member", description = "회원과 관련된 API입니다.")
public class HomeController {
    private final MemberService memberService;
    private final JwtTokenService jwtTokenService;

    @Autowired
    private ServletContext servletContext;

    RestResponse<Object> restResponse = new RestResponse<>();

    // 생성자 방식으로 의존성 주입
    @Autowired
    public HomeController(MemberService memberService, JwtTokenService jwtTokenService){
        this.memberService = memberService;
        this.jwtTokenService = jwtTokenService;
    }

    private static final Logger logger = LoggerFactory.getLogger(HomeController.class);

    /**
     * [ 로그인 하는 API ]
     * @apiNote  1. 성공적으로 로그인 했을 때
     *  / 2. 전화번호 또는 패스워드가 일치하지 않을 때, IllegalArgumentException 발생 
     * @throws IllegalArgumentException 전화번호 또는 패스워드가 일치 하지 않을 때
     */
    @ResponseBody
    @PostMapping("/login")
    public ResponseEntity login(@RequestBody MemberVO member) throws Exception {
        logger.info("[로그인 요청] Phone : " + member.getMemberPhone());
        logger.info("[로그인 요청] Password : " + member.getMemberPassword());
        // 성공적으로 로그인 했을때.
        try{
            MemberVO full_member = memberService.loginMember(member);
            String token = jwtTokenService.generateToken(Integer.toString(full_member.getMemberNumber()));
            servletContext.setAttribute(token,full_member);
            restResponse = RestResponse.builder()
                    .code(HttpStatus.OK.value())
                    .httpStatus(HttpStatus.OK)
                    .message(token)
                    .data(full_member)
                    .build();
            System.out.println(restResponse.toString());
            return new ResponseEntity<>(restResponse, restResponse.getHttpStatus());
        }
        // 이메일 또는 비밀번호가 일치하지 않음, IllegalArgumentException 발생
        catch (IllegalArgumentException e){
            restResponse = RestResponse.builder()
                    .code(HttpStatus.FORBIDDEN.value())
                    .httpStatus(HttpStatus.FORBIDDEN)
                    .message("이메일 또는 비밀번호가 틀렸습니다.")
                    .build();
            return new ResponseEntity<>(restResponse, restResponse.getHttpStatus());
        }
    }