[Spring] Swagger란? + Swagger에서 로그인 처리

백엔드 개발자로 회사에 입사하게 되면서 그동안의 개발환경과 많이 다른 환경과 맞닥뜨리게 되었다.

뭐 당연한거지만.

그 중 하나가 부트캠프에서의 프로젝트에선 백엔드와 프론트를 함께 작업했지만,

여기는 프론트개발자가 따로 있다.

따라서 여기서는 프론트엔드 개발자와 협업을 위해 제대로 된 협업도구를 사용해야한다.

그래서 그 중 하나의 툴인 Swagger에 대해서 알아보려한다.

 

Swagger란?

백엔드 API를 문서화하고, 이를 자동화하는데 사용하는 오픈소스 프레임워크다. 이제는 이름이 OpenAPI Specification(OAS)로 통합되었지만, 여전히  Swagger란 이름으로 널리 쓰이고 있다.

 

다시 쉽게 말하자면 Swagger는 아래와 같은 API 명세를 작성한다

• API 어떤  URL을 가지고 있는지
• 어떤 HTTP 메서드(GET, POST 등)를 사용하는지
• 어떤 요청값이 필요한지
• 어떤 응답이 오는지

그렇다면 스프링 부트에서 어떻게 Swagger를 사용하는지 알아보자.

---

1.스웨거 라이브러리를 추가해준다.

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

* 나는 스프링 부트 3.5.3 버전을 사용하고 있어 위와 같이 의존성을 추가해야 에러가 나지 않았다.

 

2.스웨거 화면 접속

스웨거 라이브러리만 추가해도 내부적으로 아래 2개의 URL을 자동으로 등록해준다.

• /swagger-ui/index.html  : Swaager화면(UI)를 보여주는 페이지
• /v3/api-docs : Swagger 화면이 사용할 API 명세를 제공하는 주소

그런데 그 전에 앞서 Spring Security가 이미 적용된 프로젝트라면 당연히 먼저 위 url에 대해 Security 적용 해제를 해주어야 접속이 될것이다.

@Bean
public SecurityFilterChain myFilter(HttpSecurity httpSecurity) throws Exception {
    return httpSecurity
            .cors(cors->cors.configurationSource(corsConfigurationSource()))
            .csrf(AbstractHttpConfigurer::disable) 
            .httpBasic(AbstractHttpConfigurer::disable) 
            .authorizeHttpRequests(a->a.requestMatchers("/user/login","/user/create","/swagger-ui/**","/v3/api-docs/**").permitAll().anyRequest().authenticated())
            //Security적용 제외하는 url들
            .sessionManagement(s->s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class) 
            .build();
}

 

그러고 .http://localhost:8080/swagger-ui/index.html 에 접속하면 아래처럼 화면이 뜰 것이다.

 

스웨거는 RestController와 관련한 어노테이션을 자동으로 스캔해서 문서화하기 때문에 라이브러리만 추가했음에도 

이렇게 자동 문서화가 된 것이다. 

 

 

3. 요청을 보내본다.

먼저 만들어 놓은 로그인 API를 보면, 자동으로 보낼 타입까지 인식되어있다. 

 

저기에 loginId 부분에 내 db에 있는 아이디인 user와 password인 1234를 입력해서 Execute를 누르면,

아래처럼 자동으로 응답값을 기록해준다.

 

그런데 JWT로그인을 도입했다면 아래처럼 인증이 필요한 요청에 대해서는 403에러가 뜰 것이다.

 

4.스웨거에서 JWT 로그인 인증처리

 

Security 적용해제를 해서 UI가 보이는 화면 url에는 접속이 가능했지만,

지금 보이는 댓글 생성 API에 대한 결과를 화면에 띄우기 위해서는 백엔드에 마찬가지로 HTTP요청을 보낸다. 이에 대한 응답을 받고 그 응답을 화면에 띄우는 거니까.

그래서 이런 스웨거가 보내는 요청에 대해 jwt인증 절차를 패스해줘야한다.

스웨거는 화면에서 토큰값을 직접 입력해 로그인 인증 처리를 하는 방법이 있다.

 4-1.그래서 우선 아래 스웨거 설정 클래스를 복붙한다.

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI(){
        SecurityScheme securityScheme = new SecurityScheme() //보안스키마
                .type(SecurityScheme.Type.HTTP)//HTTP방식 인증
                .scheme("bearer")//인증 방식은 Bearer
                .bearerFormat("JWT")//토큰형식을 JWT라고 명시
                .in(SecurityScheme.In.HEADER)//인증 정보를 HTTP헤더에 담아서 전송
                .name("Authorization");//인증 헤더의 이름을 Authorization
        //Security Requirement 정의
        SecurityRequirement securityRequirement = new SecurityRequirement().addList("BearerAuth");

        return new OpenAPI() //Swagger 문서를 구성하는 최상위 객체.전체 API문서의 정보와 인증,스키마 등을 설정할 수 있음. 전체 API 문서의 정보와 인증,스키마 등을 설정할 수 있음
                .info(new Info().title("내 서비스 API") //Swagger 문서의 상단에 표시되는 정보. 문서제목
                        .description("블로그용 설명 api입니다.") //문서 설명
                        .version("1.0")) //API 버전 표시
                .addSecurityItem(securityRequirement) // 앞에서 정의한 SecurityRequirement를 문서에 적용. 이걸 보고 스웨거는 모든 API호출히 jwt인증이 필요하다는 표시를하게 됨
                .schemaRequirement("BearerAuth",securityScheme); // "BearerAuth"라는 이름으로 앞에서 정의한 보안스키마를 등록

    }
}

 

위 설정으로 인해 내 서비스 API라는 전체 문서 제목과 '블로그용 설명 api입니다'라는 설명이 생겼다.

그리고 Authorize아이콘이 생겼다.

 

4-2 . 먼저 로그인 API를 실행시켜 응답값에 있는 token값을 복사하고,

4-3. 아까 생겼던 Authorize 자물쇠 버튼을 눌러 복사한 값을 붙여넣어준다.

 

그러면 아까 되지 않았던 댓글 생성 API요청에 대한 응답을 받아와 화면에 기록되는 것을 알 수 있다.

---

 

 

다음 게시물

[Spring] Swagger 어노테이션 정리