Spring Swagger(spring-doc) set

ᄋᄌᄒ·2024년 1월 21일

Spring boot Swagger https jwt_token spring doc

Spring_Project

목록 보기

1/11

📚 글 쓰기 전에

프로젝트를 하면서, 프론트와 백이 나눠져있기 때문에 명세서는 당연히 필요하다. 이를 편하게 도와주면서 postman보다 쉽게 테스트를 도와주는 것이 swagger기능이다.
오늘 쓸 글은 swagger의 몇가지 세팅을 설명하고자 한다.

본문

JWT Token

스웨거를 사용하다보면 시큐리티도 사용해야하는데 스웨거에도 액세스 토큰이나 리프레시 토큰을 담아야 다른 post,put,delete mapping mehtod들을 사용할 수 있을 것이다. 스웨거에도 jwt의 accessToken을 헤더에 넣어주는 기능이 있다.

code(SwaggerConfig.class)

	@Bean
    public OpenAPI api() {
        Info info = new Info()
                .version("v1.0.0")
                .title("API 타이틀")
                .description("API Description");

        // SecuritySecheme명
        String jwtSchemeName = "JwtAuth";
        // API 요청헤더에 인증정보 포함
        SecurityRequirement securityRequirement = new SecurityRequirement().addList(jwtSchemeName);
        // SecuritySchemes 등록
        Components components = new Components()
                .addSecuritySchemes(jwtSchemeName, new SecurityScheme()
                        .name(jwtSchemeName)
                        .type(SecurityScheme.Type.HTTP) // HTTP 방식
                        .scheme("bearer")
                        .in(SecurityScheme.In.HEADER)
                        .bearerFormat("Authorization")); // 토큰 형식을 지정하는 임의의 문자(Optional)


        return new OpenAPI()
                .info(info)
                .addSecurityItem(securityRequirement)
                .components(components);

    }

우리 프로젝트에서 인증을 헤더에서 확인하기 때문에(대부분의 프로젝트에서도 그러하고) swagger의 헤더에 인증 토큰을 넣어주는 설정이다.

result

swagger_auth
이제 상단에 이런 버튼이 생길 것이다.
auth
accessToken 값을 넣어주고 authorize버튼을 누르면 끝!

참고로 refreshToken은 쿠키에 넣어주기 때문에 알아서 재발급 시에 브라우저의 쿠키 값을 가져온다~

Https(deploy server set)

서버 배포후에 개인 도메인을 구매하고 https 설정을 스웨거에서도 해줘야할 것이다.

code 1

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.servers.Server;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
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(servers = {
        @Server(url = "https://{deployServerUrl}", description = "deploy server"))
})
@Configuration
public class SwaggerConfig {

    //..중략

    }
   
}

{deployServerUrl}에 개인이 구매한 도메인을 작성해주면 된다.

result 1

servers
이런식으로 변경이 됐을거다. request 를 하고 결과 curl을 확인하면 해당 서버로 잘 보내는 것을 확인할 수 있었다.

problem

근데 local에서 하려고 하니까, curl이 이상하다. 고정된 배포 서버로 request하는것으로 확인되는 것이다. 그러면 로컬환경에서도 가능하게끔 설정해줘야하는데..

code 2

@OpenAPIDefinition(servers = {
        @Server(url = "https://{deployServerUrl}", description = "deploy server"),
        @Server(url = "http://localhost:8080", description = "local server")
})

자료를 찾는데 생각보다 잘 안보였다. 처음에는 야믈 파일이 로컬이랑 배포서버가 읽는게 다르다보니 파일마다 서버를 다르게 읽히려고 했다만 야믈파일에서 등록한 baseurl을 읽어오기전에 빈등록이 먼저이기 때문에 에러가 발생할 것이고, 애초에 저 어노테이션 내에서 야믈파일을 읽어올 수 있는 방법이 까다로워보였다.

필자가 코드를 보다보니 해당 옵션을 잘보면 "servers="라고 되어있지 않은가! 분명 서버를 여러개 설정할 수 있을 것이다.