[Spring]API 문서화 - Swagger

 

프론트엔드와 협업을 위해 API 명세서를 작성해야 하는데..
포스트맨으로 하기 귀찮아서 Swagger를 써보자!!

📝Swagger?? 

스웨거는 RestAPI를 위한 OpenAPI 스팩에 맞춘 문서화를 도와주는 툴이다.

 

 

API 문서화

API 시각화

API 테스트

 

스웨거는 적용 즉시

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

에서 생성된 API 문서를 확인할 수 있으며 Controller 설정을 통해 만들 수 있다. 

 

 

📝Spring Swagger 기본 설정하기 

 

 

📌 의존성 설정하기 

• 먼저 의존성을 설정하자 해당 환경은 java 17이다.

	// Swagger
	implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.2.0'

 

📌SwaggerConfig 설정하기 

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Your API Title")
                        .version("1.0")
                        .description("API Description"))
                // 'access'라는 헤더를 추가
                .addSecurityItem(new SecurityRequirement().addList("access"))
                .components(new io.swagger.v3.oas.models.Components()
                        .addSecuritySchemes("access", new SecurityScheme()
                                .in(SecurityScheme.In.HEADER)  // 헤더로 설정
                                .name("access")  // 헤더 이름 설정
                                .type(SecurityScheme.Type.APIKEY)));  // scheme 없이 설정
    }
}

해당 Config는 OpenAPI에 대한 전반적인 정보와 보안 요구 사항을 설정한다 

내가 한 설정은 다음과 같다. 

• info
  • API의 기본 정보를 설정하는 부분이다. 
• addSecurityItem
  • 보안 설정을 추가하는 역할을 한다.
• components
  • API에서 사용할 보안 스키마를 정의한다.
  • 나는 JWT를 쓰기 때문에 access라는 해더를 미리 정의했다.

📌SecurityConfig 설정하기 

• 만약 Spring Security를 사용한다면 스웨거 경로도 허용해줘야 한다.

            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/login/oauth2/code/**", "/refresh", "/api/**", "/v3/api-docs/**", "/swagger-ui/**").permitAll()
                .anyRequest().authenticated())

 

 

📝Spring Swagger 만들기 

 

📌 @Tag

• 같은 이름끼리 같은 API로 묶을 수 있는 어노테이션이다.

보통 엔티티에 맞게 묶는게 편하다 .

 

@Tag(name = "알람", description = "알람 관련 API")
@RequiredArgsConstructor
@RestController
@RequestMapping("/alarm")
public class AlarmController {

 

 

 

📌@Operation

• 해당 어노테이션은 API 엔드포인트의 작업에 대한 설명을 추가하고 세부정보를 제공한다. 

    @PostMapping("/friend")
    @Operation(summary = "친구 추가 알람 생성", description = "친구 추가 요청에 대한 알람을 생성합니다.")
    public ResponseEntity<?> createFriendRequest(
        @RequestBody AlarmFriendRequestDTO alarmFriendRequestDTO,
        @AuthenticationPrincipal CustomUserDetails customUserDetails) {
        alarmService.sendFriendRequestAlarm(alarmFriendRequestDTO.receiver(), customUserDetails.getId());
        return ResponseEntity.ok().body(ResponseDto.of("친구 알람 생성 성공", null));
    }

 

 

 

📌@ApiResponse

• 해당 어노테이션은 API 응답에 대한 설명과 상태 코드를 정의한다. 
• @Operation에서 나올 수 있는 분기를 설명해주면 된다.

    @PostMapping("/friend")
    @Operation(summary = "친구 추가 알람 생성", description = "친구 추가 요청에 대한 알람을 생성합니다.")
    @ApiResponse(responseCode = "200", description = "친구 알람 생성 성공")
    @ApiResponse(responseCode = "400", description = "잘못된 요청")
    @ApiResponse(responseCode = "401", description = "인증 실패")
    public ResponseEntity<?> createFriendRequest(
        @RequestBody AlarmFriendRequestDTO alarmFriendRequestDTO,
        @AuthenticationPrincipal CustomUserDetails customUserDetails) {
        alarmService.sendFriendRequestAlarm(alarmFriendRequestDTO.receiver(), customUserDetails.getId());
        return ResponseEntity.ok().body(ResponseDto.of("친구 알람 생성 성공", null));
    }