Swagger를 연동해보자

1. 개요

개인 프로젝트를 하던 어느날 ,,,
개인 프로젝트도 API 명세서를 적어야할까? 라는 생각이 들었는데
결론은 네 ... 그럼요 ... 였다

하지만 프로젝트 진행 중 은근 시간을 많이 잡아먹는게 문서화 작업이라 너무너무 귀찮았다
그러다가 알게된 것이 바로 Swagger (이름이 참 간지난다)

2. Swagger

Swagger란?
REST API를 위한 오픈 소스 도구로,
API 명세 문서화, 관리, 테스트를 용이하게 해주는 표준 스펙

사실 Swagger를 사용하기 전에
사람들이 예시로 올려놓은 코드들을 봤는데
음 .. 뭐랄까 .. 너무 어려워? 보였다

그렇지만 계속 명세서를 따로 작성할 순 없으니 한 번 구현해보자

3. 구현

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

우선 해당 의존성을 추가해준다

id 'org.springframework.boot' version '3.5.4'

필자는 지금 굉장히 최신 버전의 스프링을 사용하고 있는데
스프링과 스웨거 사이에 의존성이 안맞으면 바로 에러를 터뜨리니

사용하는 스프링 버전을 꼭 확인해봐야 될 것 같다

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

이후로는 그냥 해당 url에 접속해주면

내 프로젝트에 있는 api들이 정리되어 있는 걸 볼 수 있다

안을 열어보면 이런식으로 되어있다

하지만 다른 사람이 봤을 때 이해하기 좋아 보이지는 않으므로
스웨거를 이쁘게 꾸며보자

@Configuration
@SecurityScheme(
	name = "JWT",
	type = SecuritySchemeType.HTTP,
	scheme = "bearer",
	bearerFormat = "JWT"
)
public class SwaggerConfig {
}

우선 필자는 JWT를 사용해 인증 인가를 진행하기 때문에
Config 클래스를 만들어 토큰을 넣어줄 준비를 해줬다

@Tag(name = "Diary API")
@SecurityRequirement(name = "JWT")
public class DiaryController {

이후 내가 구현한 클래스에 해당 어노테이션을 붙혀주면
해당 API의 이름과 토큰을 넣어주겠다고 명시해줄 수 있다

@PostMapping
	@Operation(summary = "일기 생성")
	public ResponseEntity<CreateDiaryResponseDto> createDiary(
		@AuthenticationPrincipal CustomUserPrincipal principal,
		@RequestBody @Valid CreateDiaryRequestDto requestDto
	) {
		CreateDiaryResponseDto response = diaryService.saveDiary(principal.userIdConverter(), requestDto);

		return ResponseEntity.status(HttpStatus.CREATED)
			.body(response);
	}

컨트롤러에 @Operation 어노테이션으로 각각 요청에 대한
설명을 적어둘 수도 있고

@Getter
@AllArgsConstructor
public class CreateDiaryRequestDto {

	@NotBlank(message = "제목을 입력해주세요.")
	@Size(max = 30, message = "제목은 최대 30자까지 입력 가능합니다.")
	@Schema(description = "제목", example = "title")
	private final String title;

	@NotBlank(message = "내용을 입력해주세요.")
	@Size(max = 1000, message = "내용은 최대 1000자까지 입력 가능합니다.")
	@Schema(description = "내용", example = "contents")
	private final String contents;

	@NotNull(message = "오늘의 기분을 입력해주세요.")
	@Schema(description = "감정", example = "HAPPY")
	private final Feeling feeling;
}

DTO에 @Schema 어노테이션을 통해
기본값과 설명을 넣어줄 수 있다

다시 스웨거를 실행시켜보면


이런식으로 내가 설정해둔대로 값이 잘 들어간 것을 확인할 수 있다

4. 글을 마치며

현대 기술 최고 스웨거 최고 .. !! 테스트까지 직접 할 수 있다니 .. 혁신이다 .. 지금까지는 대부분 포스트맨을 사용해서 테스트 했던 것 같은데 이렇게 좋은게 세상에 존재하다니 다들 200번씩 사용하셨으면 좋겠다.