스파르타 내일배움캠프 89일차 240102 / Swagger-UI 사용
오늘 공부한 내용
- 코드카타 2문제
- Spring 심화 프로젝트 작성
새로 알게된점
Swagger - UI 란?
- 애플리케이션의 RESTful API 문서를 자동으로 구성하는 특수 도구를 말한다.
프로젝트 내에서 지정한 url들을 아래와 같이 자동으로 문서화해준다.
이곳에서 간단히 api를 볼 수 있을 뿐만 아니라, 요청과 응답 테스트 또한 진행할 수 있다.
이런 점들이 백엔드와 프론트엔드 간의 협업과 소통을 돕는다.
Swagger - UI를 사용하기 위한 설정
build.gradle 추가 설정
의존성에 springdoc-openapi-ui를 추가한다.
dependencies {
// spring doc
implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.3.0'
}
Config 파일 구성
package com.sparta.missionreport.global.config;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@OpenAPIDefinition(info = @Info(title = "Mission Log App",
description = "Mission Log App Api 명세서",
version = "v1"))
@SecurityScheme(name = "Bearer Authentication",
type = SecuritySchemeType.HTTP,
bearerFormat = "JWT",
scheme = "Bearer")
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
.components(new Components());
}
}@Configuration 어노테이션을 통해서 OpenAPI 관련 문서를 생성하며,
@OpenAPIDefinition, @SecurityScheme 어노테이션을 SwaggerConfig에 적용하면, 위의 페이지의 Authorize버튼을 구현할 수 있다.
이 버튼은
회원정보로 발급받은 토큰을 입력하면 그 시점부터 swagger-ui에서 테스트로 보내는 요청은 모두 그 회원의 권한으로 보낼 수 있다.
로그인되지 않은 사용자, 로그인한 회원, 관리자 이러한 종류의 회원 권한들로 다양하게 요청 테스트를 진행할 수 있다.
.properties 파일 설정
# swagger
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
# spring doc
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.tags-sorter=alpha
springdoc.show-login-endpoint=true객체를 생성할 수 있는 빌더를 builder() 함수를 통해 얻고 거기에 셋팅하고자 하는 값을 셋팅하고 마지막에 build()를 통해 빌더를 작동 시켜 객체를 생성한다.
controller 설정
@Slf4j
@RestController
@RequestMapping("/api")
@RequiredArgsConstructor
@Tag(name = "2. Board Controller", description = "Board Controller")
@SecurityRequirement(name = "Bearer Authentication")
public class BoardController {
private final BoardService boardService;
@Operation(summary = "보드 생성")
@PostMapping("/boards")
public ResponseEntity<CommonResponseDto> createboard(
@AuthenticationPrincipal UserDetailsImpl userDetails,
@RequestBody @Valid BoardDto.CreateBoardRequest createBoardRequest) {
BoardDto.Response response = boardService.createBoard(userDetails.getUser(),
createBoardRequest);
return ResponseEntity.status(
HttpStatus.CREATED)
.body(new CommonResponseDto(HttpStatus.CREATED.value(), "보드가 작성되었습니다.", response));
}위의 예시는 익명게시판에서 보드를 생성하기위한 컨트롤러 의 Create 부분 이며
Controller의 상단에 @Tag 어노테이션과 @Operation 어노테이션을 추가한다.
@Tag / api 그룹 설정을 위한 어노테이션
name 속성으로 태그의 이름을 설정할 수 있고, description 속성으로 태그에 대한 설명을 추가할 수 있다.
@Tag에 설정된 name이 같은 것 끼리 하나의 api 그룹으로 묶게 된다.
@Operation / api 상세 정보 설정을 위한 어노테이션
summary 속성으로 api에 대한 간략한 설명, description 속성으로 api에 대한 상세 설명을 추가할 수 있으며, responses, parameters 속성 등을 추가로 적용할 수 있다.
Request, Response 객체 설정
public class BoardDto {
@Getter
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "보드 생성 요청 dto")
public static class CreateBoardRequest {
@NotBlank
@Schema(description = "보드 이름", defaultValue = "개발 전체 진행 완료하자")
private String name;
public Board toEntity(User createdBy) {
return Board.builder().name(name).createdBy(createdBy).build();
}
}
@Getter
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "보드 수정 요청 dto")
public static class UpdateBoardRequest {
@Schema(description = "보드 이름", defaultValue = "보드 이름 수정 test")
private String name;
@Schema(description = "보드 색상", defaultValue = "blue")
private Color color;
@Schema(description = "보드 설명", defaultValue = "보드, 수정 완료하기")
private String description;
@Schema(description = "보드 마감 일자", defaultValue = "2023-01-03 09:00")
@JsonFormat(pattern = "yyyy-MM-dd HH:mm")
private LocalDateTime deadLine;
}
@Getter
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "보드 정보 반환 dto")
public static class Response {
@Schema(description = "보드 id", defaultValue = "1L")
private Long id;
@Schema(description = "보드 이름", defaultValue = "제발...문제없이 작동해주세요")
private String name;
@Schema(description = "보드 설명", defaultValue = "카드, 댓글 기능 구현 완료하기")
private String description;
@Schema(description = "카드 색상", example = "red")
private String color;
@Schema(description = "생성 유저 이메일", defaultValue = "sparta@gmail.com")
private String createdBy;
@Schema(description = "보드 작업자 리스트", defaultValue = "[\"spsta@gmail.com\", \"worker1@gmail.com\",\"worker2@gmail.com\"]")
private List<String> boardWorkers;
@Schema(description = "보드 생성 일자", defaultValue = "2023-01-01T00:00:00")
private LocalDateTime createdAt;
public static BoardDto.Response of(Board board) {
return Response.builder()
.id(board.getId())
.name(board.getName())
.description(board.getDescription())
.color(board.getColor().getColor())
.createdBy(board.getCreatedBy().getEmail())
.boardWorkers(board.getBoardWorkerList().stream().map(BoardWorker::getUserEmail)
.toList())
.createdAt(board.getCreatedAt())
.build();
}
}
}위의 예시처럼 @Schema 를 이용하여 각부분의 설명, 기본값을 설정하여 기입할수 있다.
@Schema / Request, Response 객체에 대한 설정을 위한 어노테이션
description으로 설명을 추가할 수 있고, defaultValue으로 기본적으로 사용할 값을 설정할 수 있으며, example을 통해 예시를 설정할 수도 있다.
느낀점
Postman이 아닌 Swagger-UI 라는 새로운 API 테스트 프로그램을 프로젝트 하면서 배우게 되었다.
혼자 작성해서 확인해야하는 Postman에 비해 Swagger-UI는 코드 작성시 팀원들과 토의로 일정 규칙하에 작성하면 기본값을 설정한상태로 테스트가 가능하기에 좀더 효율적으로 시행할수 있다.
프로젝트를 하면서 팀원들에게 새로운 것을 배울때 마다 감사를 느끼며 더욱더 열심히 해야겠다고 생각한다.