Swagger을 통한 문서자동화 기능 사용

Swagger API를 통해 API 명세서를 편리하게 관리 할 수 있음

아래 예시는 Swagger doc을 이용해서 Swagger API 관리를 해보았다

Swagger를 적용하면 아래 그림과 같이 API 명세서를 만들 수 있고, JSON 데이터로 묶어서 api 정보를 관리 할 수 있다.

왼쪽 : http://localhost:8080/swagger-ui.html  / 오른쪽 : http://localhost:8080/api-docs

 

 

 

적용방법

1. gradle에 의존성 주입

	dependencies {
		implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'
	}

 

2. application.yml 에 추가

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    groups-order: DESC
    operationsSorter: method
    disable-swagger-default-url: true
    display-request-duration: true
  api-docs:
    path: /api-docs
  show-actuator: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  paths-to-match:
    - /**

 

 

3. SwaggerConfig 파일 생성하여 API 명세서 선언, path 설정

package com.turkey.walkingwith7puppy.config;

import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import lombok.RequiredArgsConstructor;


@OpenAPIDefinition( // Swagger 문서에 대한 메타데이터 정의
	info = @Info(title = "WWP API 명세서",
		description = "반려견 메이트 찾기 서비스 API 명세서",
		version = "v1"))
@RequiredArgsConstructor
@Configuration
public class SwaggerConfig {

	@Bean
	public GroupedOpenApi wwpOpenApi() {
		String[] paths = { "/**" };
		return GroupedOpenApi.builder()
			.group("WWP 서비스 API")
			.pathsToMatch(paths)
			.build();
	}

}

4. 적용하려는 controller 클래스의 메소드에 @Operation , @ApiResponse 추가

 

@RestController
@RequiredArgsConstructor
public class MemberController {

    private final MemberService memberService;

    @Operation(summary = "회원 탈퇴 요청", description = "회원 정보가 삭제됩니다.", tags = { "Member Controller" })
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "OK",
            content = @Content(schema = @Schema(implementation = Void.class))),
        @ApiResponse(responseCode = "400", description = "BAD REQUEST"),
        @ApiResponse(responseCode = "404", description = "NOT FOUND"),
        @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR")
    })
    @PostMapping("/user/signup")
    public ResponseEntity<Void> signup(
        @Parameter(description = "회원가입", required = true, example = "1")
        @RequestBody @Valid final MemberSignupRequest memberSignupRequest) {

        memberService.signup(memberSignupRequest);
        return ResponseEntity.status(HttpStatus.OK).body(null);
    }

 

5. Spring Security를 사용한다면 filter에 path 설정해주고 permit 추가

 

@Configuration
@RequiredArgsConstructor
@EnableWebSecurity
public class WebSecurityConfig {

    private final JwtUtil jwtUtil;
    private final JwtAuthFilter jwtAuthFilter;

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {

        return http
            .csrf().disable()
            .httpBasic().disable()
            .formLogin().disable()
            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            .and()
            .cors()
            .and()
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(PathRequest.toStaticResources().atCommonLocations()).permitAll()
                .antMatchers("/user/**").permitAll()
                .antMatchers(HttpMethod.GET, "/boards/**").permitAll()
                //Swagger doc관련 코드
                .antMatchers("/v3/api-docs/**", "/swagger-ui.html", "/swagger-ui/**", "/webjars/**","/api-docs/**","favicon.ico", "/swagger/**", "/swagger-resource/**").permitAll()
                .anyRequest().authenticated()
                .and()
                .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class)
            )
            .anonymous().disable()
            .build();
    }
}