Swagger 관련 공통 설정 수행 ( @OpenAPIDefinition )

@OpenAPIDefinition
。@Configuration 클래스에 선언하여 OpenAPI Specification에 따르는 어플리케이션의 API 문서에 대한 정보를 선언된 클래스에서 설정하도록하는 어노테이션

• info = @Info(설정)
  。어플리케이션 API 에 대한 title, version, description 등을 설정하는 @Info 어노테이션을 설정

@Configuration
@OpenAPIDefinition(
	 info = @Info(
		 title = "테크업 쇼핑몰",
		 version = "0.0.1",
		 description = "테크업 쇼핑몰 API 명세  "
	 )
)

▶ API 문서 상단에 다음 설정이 정의

Swagger로 구축한 API 문서에 JWT 토큰을 등록할 Authorization 버튼 생성 및 Header에 포함하도록 설정하기
。해당 기능을 통해 JWT 토큰을 입력 시 향후 Swagger에서 수행하는 API 요청에 자동으로 토큰이 인증헤더에 추가

• @Configuration 클래스 내 OpenAPI 객체에 설정을 정의한 후 @Bean을 통해 Spring Bean으로 등록

	@Bean
	public OpenAPI openAPI() {
		return new OpenAPI()
			.components(
				new Components()
					.addSecuritySchemes(
						"Bearer Authentication", // 키명
						new SecurityScheme()
							.type(SecurityScheme.Type.HTTP)
							.scheme("bearer")
							.bearerFormat("JWT")
					)
			);
	}

▶ "Bearer Authentication"는 키명으로서 적용할 컨트롤러 클래스에 @SecurityRequirement(name = "Bearer Authentication")으로 선언하여 Swagger API 전송 시 헤더에 토큰을 포함하도록 설정


▶ 우측에 Authorize 버튼이 생성되었으며 클릭 시 JWT 토큰값을 입력하는 창이 도출

• Swagger에서 추가된 JWT토큰을 HTTP Request의 Authorization Header에 추가하도록 해당 컨트롤러에 @SecurityRequirement(name = "키명")을 지정
  
  。@SecurityRequirement(name = "Bearer Authentication")를 @Controller 클래스의 Controller 별로 설정하여 해당 JWT 토큰을 요구하도록 설정가능
  ▶ .addSecuritySchemes()에서 지정된 key명을 name으로 설정
  
  。이후 Swagger로 API 요청 시 해당 API 요청에 Swagger에서 추가한 JWT토큰이 포함되어 전송됨
  
  
• 별도로 JWT 토큰을 요구하는 Controller에 대해서만 JWT 토큰 추가 시 사용하도록 설정하기

	 @GetMapping("/{id}")
	@ResponseStatus(HttpStatus.OK)
	@SecurityRequirement(name = "Bearer Authentication")
	public MemberResponse.Details detail(@PathVariable Long id){
		return memberservice.getMember(id);
	}

▶ 해당 API에 대해서 사용 시 JWT 토큰을 사전에 설정해야 사용가능

Swagger에서 프로필 환경 별 서버 접속 설정
Profile

。Swagger 접속 시 어플리케이션에서 활성화된 프로필에 따라 각각 서버에 대한 API를 구분해서 도출하도록 설정
▶ dev 환경에서 prod 환경 서버로 API 요청을 전송하는것을 방지하기 위해 설정.

• @Configuration 클래스 내 OpenAPI 객체에 설정을 정의한 후 @Bean을 통해 Spring Bean으로 등록
  。Enviroment 객체를 주입받아서 현재 활성화 된 프로필 가져오기
  ▶ switch 문에 따라 프로필 별로 URL을 전달

@Configuration
@RequiredArgsConstructor
public class SwaggerConfiguration {
	private final Environment environment;
	private String getServerUrl(){
		// 현재 활성화된 프로필 가져오기
		String profile = environment.getActiveProfiles()[0];
		// 활성화 된 프로필별로 각각의 서버 URL을 반환
		return switch(profile){
			case "dev" -> "http://localhost:8081";
			case "test" -> "http://localhost:8082";
			default -> "http://localhost:8080";
		};
	}
	@Bean
	public OpenAPI openAPI() {
		return new OpenAPI()
			.servers(
					List.of(new Server().url(getServerUrl())
				)
			);
	}
}

▶ test로 프로필 설정 시 swagger에서 http://localhost:8082로 접속되었음을 확인 가능

Swagger 내 API를 그룹별로 분리하기
。해당 API들을 URL 패턴별로 그룹으로 분리를 수행
ex ) /users/...로 시작하는 API만 따로 그룹으로 분리

• @Configuration 클래스 내 GroupedOpenApi 객체에 대한 설정을 정의 후 Spring Bean으로 등록
  ▶ 해당 객체는 builder 패턴으로 정의되어있으므로 GroupedOpenApi.builder()...으로 설정을 수행하면 됨.
  
  
• GroupedOpenApi.pathsToMatch("/URL패턴1", "/URL패턴2" , ... )
  。해당 URL패턴을 가지는 API를 대상으로 별도의 그룹으로 분리
  
  。 분리 시 중복을 방지하기위해 다른 API 그룹을 정의하는 GroupedOpenApi에 대해서 GroupedOpenApi.pathsToExclude("/URL패턴/**")를 정의해야함.
  
  。URL 엔드포인트 중간에 PathVariable을 포함하는 경우 다음처럼 *로 표시
  ▶ /api/posts/{id}/comments인 경우 /api/posts/*/comments로 설정

@Bean
    public GroupedOpenApi commentApi(){
        return GroupedOpenApi.builder()
                .pathsToMatch("/api/posts/*/comments/**","/api/requests/*/comments/**")
                .group("Comment API")
                .build();
    }

• GroupedOpenApi.pathsToExclude("/URL패턴1", "/URL패턴2" , ...)
  。해당 URL패턴을 가지는 API를 그룹에서 제외하도록 설정

	@Bean
    public GroupedOpenApi userApi(){
        return GroupedOpenApi.builder()
				// 해당 URL 패턴을 가지는 API만 포함
                .pathsToMatch("/api/v1/users/**")
       			// 해당 URL 패턴을 제외한 API만 포함
       			.pathsToExclude("/api/v1/users/me/friends/**", "/api/v1/users/me/npcs/**", "/api/v1/users/me/inventory/**")
                .group("유저")
                .build();
    }

▶ 설정된 URL 패턴을 가지는 API만 따로 표시하는것을 확인 가능