SpringBoot Swagger (API 명세서) + Spring security

API 명세서에 포함되어야 하는 내용

 

1. API 이름과 설명

 

2. URL 및 HTTP 메서드 (GET /users, POST /users, DELETE /users, PUT /users)

 

3. 요청

헤더: 요청에 필요한 인증 정보나 메타데이터

파라미터: 쿼리 파라미터, 요청 Body에 들어갈 데이터 (JSON)

 

4. 응답 : HTTP 상태 코드 (성공 또는 실패)

 

5. 에러처리 : 실패시 반환되는 에러코드와 메세지 정의 (404)

 

 

RESTFUL API 설계를 위해 정말 중요한 작업이지만, 일일이 작성하기 너무 귀찮다.

Spring boot에서는 Swagger를 사용해 api명세서를 쉽게 작성할 수 있다.

 

 

build.gradle에 의존성을 추가하면 된다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
implementation 'org.springframework.boot:spring-boot-starter-security' //생략 가능
testImplementation 'org.springframework.security:spring-security-test' //생략 가능

openapi 라이브러리와 spring security이다. 스프링 3.x 버전이면 2.0.2 이상을 사용해야 한다.

application.properties에도 swagger 설정을 추가해야 한다.

springdoc.api-docs.enabled=true
springdoc.swagger-ui.enabled=true

 

이제 gradle과 ide를 동기화 해준다음 gradle build를 하면 필요한 라이브러리가 추가된다.

 

swagger 설정은 커스터마이징 가능하다.(생략 가능)

package com.example.crud.controller;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {	//커스터마이징

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("CRUD API")
                        .version("1.00")
                        .description("API 명세서")
                );
    }
}

 

security 설정은 안 해도 되긴 한데 나는 그냥 했다. 둘이 보통 세트인 것 같다.

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception{
        http.csrf((csrf) -> csrf.disable());

        http.sessionManagement((sessionManagement) ->
                sessionManagement.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
        );

        http.authorizeHttpRequests((authorizeHttpRequests) ->
                authorizeHttpRequests
                        .requestMatchers("/v3/api-docs/**", "/swagger-ui/**").permitAll()

                        .anyRequest().authenticated()
        );

        return http.build();
    }

 

HttpSecurity :

Spring Security의 핵심 클래스로 HTTP요청에 대한 보안 정책을 정의한다.

 

.permitAll()는 인증 없이도 접근 가능한 주소들이다. swagger 주소들을 여기에 추가해준다.

.anyRequest().authenticated()는 위에서 명시되지 않은 모든 요청에 대해 인증이 필요하도록 설정한다.

리턴값은 build()로 반환한다. HttpSequrity는 빌더 패턴이 내장되어있어서 보안 설정을 단계적으로 작성 가능하다.

 

여기까지 작성하고 gradle build() 다시 하고

gradle bootrun으로 서버 실행해서

http://localhost:8080/swagger-ui/index.html
이 주소로 가면 swagger를 이용할 수 있다.

이처럼 내가 사용 중인 api를 한눈에 모아볼 수 있다.

 

http://localhost:8080/v3/api-docs

여기로 가면,

spring boot 웹 애플리케이션의 api를 OpenAPI 3을 이용하여 json으로 형식화 한 것을 볼 수 있다.