[Spring] Swagger 설정

Swagger 설정으로 API 명세서 자동 생성하기

이번 글에서 Spring Boot 프로젝트에서 Swagger (OpenAPI)를 설정하여 API 명세서를 자동 생성하는 방법을 소개하겠습니다. 

Swagger 설정은 개발자들이 API를 쉽게 이해하고 사용할 수 있도록 도와주는 중요한 도구입니다!

 

 

0. 프로젝트 생성 시 의존성 추가

Spring Boot 프로젝트 생성 시, 필수적으로 추가하거나 사용 목적에 따라 선택적으로 추가하곤 합니다!

앞선 글에서 프로젝트 의존성에 대한 내용을 작성해놓았지만, 

Swagger에 대한 Dependency만 보자면 다음과 같습니다!

    // Swagger
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

 

 

1. Swagger 설정

API 명세서를 자동 생성하기 위해 Swagger(OpenAPI)를 설정하기 위해서는 @OpenAPIDefinition과 같은 어노테이션을 사용하여 기본 정보를 정의하고, 설정 클래스를 통해 OpenAPI 객체를 반환하는 방식으로 구현합니다. 

 

아래는 제가 프로젝트에서 활용했던 Swagger 전체 코드입니다!

@OpenAPIDefinition(info = @Info(
	title = "SemBot API",
	description = "SemBot 명세서",
	version = "v1.0.0"))
@Configuration
public class SwaggerConfig {
	@Bean
	public OpenAPI openApi() {
		String jwt = "JWT";
		SecurityRequirement securityRequirement = new SecurityRequirement().addList("JWT");
		Components components = new Components().addSecuritySchemes(jwt, new SecurityScheme()
			.name(jwt)
			.type(SecurityScheme.Type.HTTP)
			.scheme("bearer")
			.bearerFormat("JWT")
		);

		return new OpenAPI()
			.addServersItem(new Server().url("/"))
			.addSecurityItem(securityRequirement)
			.components(components);
	}
}

 

위의 설정 코드는 Swagger UI를 통해 API 명세서를 자동으로 생성하고, 

JWT 인증 방식을 사용하여 API 보안을 설정합니다. 

 

이제 각 코드에 대하여 자세하게 살펴보겠습니다!! 🔍

 

 

2. 어노테이션 설명

• @OpenAPIDefinition
  • Swagger API 문서의 기본 정보를 설정하는 어노테이션
  • API의 제목, 설명, 버전 등의 정보를 제공
  • title: API 문서의 제목
  • description: API 문서의 설명
  • version: API 버전 정보 (초기에는 v1.0.0)
• @Configuration
  • 이 클래스가 Spring의 설정 클래스임을 나타냄
  • Bean 정의를 포함하는 클래스임을 Spring에게 알림

 

 

3. Swagger 설정 코드 설명

3-1. JWT 보안 설정

String jwt = "JWT";
SecurityRequirement securityRequirement = new SecurityRequirement().addList("JWT");

 

이 부분은 JWT 인증 방식을 사용함을 명시합니다.

SecurityRequirement 객체에 "JWT"를 추가하여 API 요청 시 JWT 토큰이 필요함을 설정합니다.

이렇게 설정함으로써 인증되지 않은 요청을 차단하고 보안을 강화할 수 있습니다.

 

 

3-2. 보안 스키마 설정

Components components = new Components().addSecuritySchemes(jwt, new SecurityScheme()
    .name(jwt)
    .type(SecurityScheme.Type.HTTP)
    .scheme("bearer")
    .bearerFormat("JWT")
);

 

Components 객체를 사용하여 보안 스키마를 정의합니다. 여기서는 JWT를 사용한 Bearer 인증 방식을 설정했습니다.

• name : 보안 스키마의 이름
• type : HTTP 인증 방식 사용
• scheme : Bearer 인증 방식 사용
• bearerFormat : JWT 형식 사용

 

 

3-3. OpenAPI 설정

return new OpenAPI()
    .addServersItem(new Server().url("/"))
    .addSecurityItem(securityRequirement)
    .components(components);

• addServersItem : API 서버 URL 설정 (루트 경로 "/")
• addSecurityItem : 보안 요구사항 추가
• components : 보안 스키마 컴포넌트 추가

 

 

4. 결론

다음과 같이 설정하면 http://localhost:8080/swagger-ui/index.html로 이동하게 되면 다음과 같이 손쉽게 API 문서를 확인하실 수 있습니다. 

 

이렇게 Swagger 와 JWT를 활용하여 Spring Boot 프로젝트의 API 명세서를 자동으로 생성하고, 보안을 강화하는 방법을 알아보았습니다. 

 

Swagger는 개발자들 간의 원활한 소통과 API 사용의 편리함을 제공하고, JWT 인증 방식은 API의 보안을 강화하여 안전하게 서비스를 제공할 수 있도록 도와주니 유용하게 사용해보시길 바랍니다! 😍