Swagger

박영준·2023년 8월 22일

프로젝트

프로젝트에 도움되는 지식

목록 보기

7/16

1. 정의

개발한 Rest API 를 편리하게 문서화
API들이 가지고 있는 스펙(spec)을 명세, 관리할 수 있는 프로젝트/문서
협업 진행 시, 이미 만들어진 프로젝트에 대한 유지보수를 할 때 구축된 API 서버가 어떤 스펙을 가지고 있는지 파악하고 싶은 경우에 사용

2. 구현

1) 의존성 추가

Springboot에서 Swagger를 사용하면, 컨트롤러에 명시된 어노테이션을 해석하여 API문서를 자동으로 만들어준다.

dependencies {
    // Swagger
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
}

단, SpringBoot 버전과 Swagger 의 버전을 맞추는 것이 중요하다!
내가 사용한 SpringBoot 는 3.1.2 버전, Swagger 는 3.0 버전이다.

아래와 같은 에러 메시지가 나타날 수 있는데, 이는 springfox swagger가 javax 패키지를 jakarta로 변경하지 않아서 생기는 문제다.
type javax.servlet.http.httpservletrequest not present

2) WebSecurityConfig

spring security 사용했기 때문에, 접근 권한 설정이 필요하다.

public class WebSecurityConfig {
	...

	@Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.csrf((csrf) -> csrf.disable());

        ...

        http.authorizeHttpRequests((authorizeHttpRequests) ->
                        authorizeHttpRequests
                                ...

                                .requestMatchers("/v3/**", "/swagger-ui/**").permitAll()        // swagger
                                .anyRequest().authenticated() 		// 그 외 요청은 인증 필요
        );
        
        // 필터 관리
        ...

        return http.build();
    }
}

v3 는 SpringBoot 의 버전을 뜻한다.

1), 2) 만으로도 Swagger 사용이 가능하다.
그러나 Swagger 문서를 SwaggerConfig 를 이용해서 커스텀해줄 수 있다.

3) SwaggerConfig

SwaggerConfig 를 통해, 세부적으로 각 Controller 의 API 요청마다 적용을 해줄 수 있다.

@OpenAPIDefinition(
        info = @Info(title = "오늘 이곳(OE) Project API",
                description = "5조 실전 프로젝트 오늘 이곳(OE) Project API 명세서",
                version = "v1"))
@Configuration
public class SwaggerConfig {
	// 세부적으로 설정을 해줄 수도 있다.
}

4) Controller

그 중 MessageRoomController 를 예시로 들어보자.

@RequiredArgsConstructor
@RestController
@RequestMapping("/api")
public class MessageRoomController {
    private final MessageRoomService messageRoomService;

    @Operation(summary = "쪽지방 생성", description = "특정 쪽지방을 생성합니다.")
    @PostMapping("/room")
    public MessageResponseDto createRoom(@RequestBody MessageRequestDto messageRequestDto, @AuthenticationPrincipal UserDetailsImpl userDetails) {
        return messageRoomService.createRoom(messageRequestDto, userDetails.getUser());
    }

    @Operation(summary = "쪽지방 전체 조회", description = "사용자 자신과 관련된 쪽지방 목록을 조회합니다.")
    @GetMapping("/rooms")
    public List<MessageResponseDto> findAllRoomByUser(@AuthenticationPrincipal UserDetailsImpl userDetails) {
        return messageRoomService.findAllRoomByUser(userDetails.getUser());
    }

    @Operation(summary = "쪽지방 선택 조회", description = "사용자 자신과 관련된 쪽지방을 선택 조회합니다.")
    @GetMapping("room/{roomId}")
    public MessageRoomDto findRoom(
            @Parameter(description = "roomId", required = true, example = "9e648d2d-5e2e-42b3-82fc-b8bef8111cbe")  @PathVariable String roomId, @AuthenticationPrincipal UserDetailsImpl userDetails) {
        return messageRoomService.findRoom(roomId, userDetails.getUser());
    }

    @Operation(summary = "쪽지방 삭제", description = "특정 쪽지방을 삭제합니다.")
    @DeleteMapping("room/{id}")
    public MsgResponseDto deleteRoom(@PathVariable Long id, @AuthenticationPrincipal UserDetailsImpl userDetails) {
        return messageRoomService.deleteRoom(id, userDetails.getUser());
    }
}