스웨거(Swagger)
오늘은 프로젝트 기능 구현 중 웹소켓에 대해 알아보다가 도저히 혼자 도전을 못할 것 같아, 다른 기능을 찾아보다가 스프링 스웨거를 하기로 마음먹었다.
스웨거란?
스웨거(Swagger)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태걔의 지원을 받는 오픈 소스 스프트웨어 프레임워크이다.
더 간단하게 말하면, 백엔드에서 구현한 RestApi를 프론트에서 쉽게 확인하기 위해서 만드는 기능 구현이다.
오늘은 과제 때 만든 프로젝트에 스웨거를 한번 추가해보는 작업을 해보았다.
우선 Swagger를 사용하기 위해서 build.gradle에 의존성을 추가해주어야한다.
// Swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'그레이들에 의존성을 추가해주고, 재 실행을 한다.
다음은 SwaggerConfig 클래스를 만든다.
SwaggerConfig Class
@OpenAPIDefinition(
info = @Info(title = "블로그 API 명세서",
description = "블로그의 CRUD 기능을 자세히 보여주는 API입니다.",
version = "v3"))
@RequiredArgsConstructor
@Configuration
public class SwaggerConfig {
}그리고 WebSecurityConfig에 스웨거를 허용해주기 위해 코드를 추가한다.
.requestMatchers(
"/",
"/v3/api-docs/**",
"swagger-ui/**").permitAll() // swagger 요청 추가유저의 API 정보는 보여지면 안좋기 때문에, 유저컨트롤러에 회원가입하는 api에는 스웨거에 표시되지않게 어노테이션을 달아주자.
@Operation(hidden = true) //PostMapping 위에 추가깜빡하고 작성을 안했는데, application.properties에도 설정을 따로 해주어야한다.
application.properties
springdoc.packages-to-scan=com.sparta.blog
springdoc.default-consumes-media-type=application/json;charset=UTF-8
springdoc.default-produces-media-type=application/json;charset=UTF-8
springdoc.swagger-ui.path=/
springdoc.swagger-ui.disable-swagger-default-url=true
springdoc.swagger-ui.display-request-duration=true
springdoc.swagger-ui.operations-sorter=alpha위 코드를 추가해준다.
이제 이 상태로 실행을 돌리면, URL: http://localhost:8080/swagger-ui/index.html
으로 접속을하면 swagger화면이 보여야한다.
하지만 화면은..
이렇게 토큰이 유효하지 않다 뜨는데, 우리가 과제를 하면서 토큰 검증 기능을 추가해주었기 때문에
로그인과 회원가입을 제외한 api에서는 토큰 검증이 들어가게끔 설정을 해두었다.
필터단을 확인해보자.
이런식으로 토큰이 없을 때, 그리고 발급된 토큰이 정상값이 아닐 때 토큰이 유효하지 않다는 예외처리가 발생하게 구현하였다.
그럼 여기서 로그인과 회원가입시에는 검증이 필요하지않게 걸어두었으니, 그 부분에 스웨거도 검증이 필요하지않다고
같이 걸어주면 될 것 같다.
if ("/api/auth/login".equals(req.getRequestURI()) ||
"/api/auth/signup".equals(req.getRequestURI()) ||
req.getRequestURI().startsWith( "/v3/") ||
req.getRequestURI().startsWith("/swagger-ui")) {
// 토큰이 비어 있을 때 예외 처리를 하지 않도록 조건문 추가
filterChain.doFilter(req, res);
return;
}조건에 로그인 회원가입 뿐만아니라, 스웨거로 이동할때도 토큰 검증을 받지 않겠다고 코드를 수정하였다.
그 다음 재 실행을 했더니, 이렇게 Api 명세서가 한번에 확인 할 수 있는 스웨거 화면이 나왔다.
SwaggerConfig 클래스에서 제목과 내용도 넣어주었더니 블로그 API 명세서라고 잘 들어왔다.
오늘은 이렇게 Swagger를 사용하는 방법을 알아보았다.
