[Spring, Swagger] Swagger 적용하기 및 기본 경로 변경하기

몇 달 전 새로운 프로젝트를 시작하기 앞서 백엔드에서 작업하는 내용을 프론트 개발자들이 직접 확인할 수 있도록 Swagger를 통해 문서화를 진행하기로 했다 ! 문서화를 해놓으면 요청하는 데이터의 타입과 변수명을 직접 확인할 수 있고, 응답되는 타입과 값을 바로바로 확인할 수 있어 소통의 비용이 감소할 수 있습니다 ! 멋쟁이 프론트 개발자가 Swagger에 백엔드 개발자가 문서화한 내용들을  프로젝트 내부에서  모두 가져다 쓸 수 있도록 제작해놔서 코드 제작에 대한 비용도 감소하였다 !

그럼 이제 Swagger 적용 방법에 대해 알아보도록 합시다 !

 

🫡Swagger 적용하기

프로젝트 환경

Java : 17

Spring-boot : 3.2.7

Gradle : 8.8

SpringBoot 3.0.0 이상부터는 springfox가 아닌 springdoc-openapi-ui 라이브러리를 사용해야 됩니다 !

 

먼저 dependencies를 추가해줍니다 !

// Gradle

implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.0.2'

// Maven

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

 

Swagger 문서에서 API 보안을 적용하기 위해 아래와 같이 구성해 놓았고 각각의 설정에 대해 설명해 드리겠습니다 !

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
        info = @Info(title = " API 명세서",
                description = "API 명세서",
                version = "v1"))
@Configuration
public class SwaggerConfig   {

    @Bean
    public OpenAPI api() {
        SecurityScheme apiKey = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .in(SecurityScheme.In.HEADER)
                .name("Authorization")
                .scheme("bearer")
                .bearerFormat("JWT");

        SecurityRequirement securityRequirement = new SecurityRequirement()
                .addList("Bearer Token");

        return new OpenAPI()
                .components(new Components().addSecuritySchemes("Bearer Token", apiKey))
                .addSecurityItem(securityRequirement);
    }
}

• SecurityScheme : Swagger를 통해 제공되는 API가 JWT(JSON Web Token) 인증 방식을 사용하고 있읐음 정의하고, HTTP기반 인증 방식을 사용한다는 의미입니다. 요청 시 Authorization 헤더에서 토큰을 전달하고도록 설정하고 토큰의 인증 방식이 Bearer Token임을 명시합니다. 마지막으로 Bearer Token의 형식이 JWT임을 선언해 놓은 내용입니다.
• SecurityRequirement : API에 접근하려면 "Bearer Token"이라는 이름의 Security Scheme를 요구합ㄴ디ㅏ. 즉, 클라이언트가 API 요청을 보낼 때 JWT를 Authorization 헤더에 포함해야 한다는 의미입니다.

마지막으로 OpenAPI 객체에 해당 내용을 추가해 Swagger UI에서 API 호출 시 인증을 위해 JWT 토큰을 입력할 수 있는 창이 표시되고, 클라이언트는 토큰을 제공해야만 API에 접근할 수 있습니다 !

 

여기까지 모두 설정하셨다면 ! 스웨거의 기본 경로를 통해 Swagger UI에 접속이 가능합니다 !

* 기본 경로 : http:localhost:8888/swagger-ui/index.html 

 

🚦Swagger 경로 변경하기

Swagger의 기본 경로는 모두 동일하기 때문에 외부에서 기본 경로로 접근했을 경우 정보가 바로 노출될 수 있는 위험이 있습니다 !

이를 방지하기 위해 기본 경로에서 제가 원하는 URI로 변경하고 싶어 방법을 찾아봤습니다 !

application.properties에 아래 내용을 추가해주면 간단하게 변경할 수 있습니다 !

## swagger
springdoc.api-docs.path=/aaa/bbb/v3/api-docs
springdoc.swagger-ui.path=/aaa/bbb/swagger-ui.html
springdoc.swagger-ui.url=/aaa/bbb/v3/api-docs

 

URI는 원하는 경로로 작성하면됩니다 ! 설정에 대해 더 궁금한 사항은 Documente를 참고하세요 !

OpenAPI 3 Library for spring-boot

 

경로 바꾸려고 이것 저것 많이 찾아보고 헤맸는데 3가지를 모두 작성해줘야 정상적으로 작동된다니.... 그래도 해결 할 수 있어서 편안하네요 !