SpringBoot에 Swagger 끼얹기

Node.js를 사용하면서 Swagger를 배웠다.

스프링 부트에도 적용해봤다.

 

 

1. 의존성 추가

의존성은 Gradle로 작업했다.

Maven이면 Maven 의존성을 추가하면 된다.

 

dependencies { 
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'
    implementation 'io.springfox:springfox-swagger2:2.9.2'
}

 

추가 후 이클립스 기준으로 프로젝트 오른쪽 클릭 → Gradle → Refresh Gradle Project 메뉴를 클릭하여 의존성 체크를 해주자.

 

 

2. Swagger Config 작성

Swagger 설정 파일을 작성해주자.

config 패키지를 만들고, swagger 패키지를 만들어서 그 안에 SwaggerConfiguration 이름으로 클래스 파일을 만들었다.

 

그리고 설정 내용을 작성하자.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
	
	/**
	 * 스웨거 API 문서 생성
	 * @author Johnny
	 * @return Docket
	 */
	@Bean
	public Docket swaggerAPI() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(this.swaggerInfo()) // 스웨거 정보 등록
				.select() 
				.apis(RequestHandlerSelectors.any()) // 모든 controller들이 있는 패키지를 탐색해서 API문서를 만든다.
				.paths(PathSelectors.any())
				.build()
				.useDefaultResponseMessages(true); // 기본으로 세팅되는 200, 401, 403, 404 메시지 표시
	}
	
	/**
	 * 스웨거 정보
	 * @author Johnny
	 * @return ApiInfo 
	 */
	private ApiInfo swaggerInfo() {
		return new ApiInfoBuilder()
				.title("Spring Boot API Documentation")
				.description("Spring Boot 프로젝트 기본 구조를 잡는 프로젝트 입니다.")
				.version("1.0.0")
				.build();
	}
}

 

spring.web.plugins의 Docket 클래스를 반환하는 swaggerAPI 메소드를 만들었다.

 

swaggerInfo는 Docket 클래스를 만들 때 추가하는 프로젝트 정보다.

 

 

3. 컨트롤러 작성

API 문서를 만들기 위해 컨트롤러를 만들어서 작성해보자.

 

컨트롤러 안에 다음과 같은 코드를 추가하자.

import java.util.List;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.johnny.demo.domain.member.model.MemberDTORes;
import com.johnny.demo.domain.member.service.MemberServiceImple;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.AllArgsConstructor;

@Api(tags = {"1. Member"}) // MemberController를 대표하는 타이틀 영역에 표시될 정보
@AllArgsConstructor
@RestController
@RequestMapping(value="/member")
public class MemberController {
	
	private MemberServiceImple memberService;
	
	/**
	 * 전체 회원 조회 요청
	 * @author Johnny
	 * @return List<MemberDTORes>
	 */
	@ApiOperation(value="전체 회원 조회", notes="모든 회원을 조회합니다.")
	@GetMapping("/findAll")
	public List<MemberDTORes> findAllMember(HttpServletRequest req, HttpServletResponse res) {
		return memberService.findAllMember();
	}
}

io.swagger.annotations 패키지의 @Api 어노테이션은 컨트롤러를 대표하는 타이틀을 작성하기 위해 사용한다.

GET 요청 메소드에 @ApiOperation 어노테이션이 작성되었는데, 이는 URI(유니폼 리소스 식별자)에 대한 제목과 설명을 작성할 수 있다.

 

 

 

 

이렇게 하고 서버를 실행시켜서 다음과 같은 URL에 접속해보자.

http://localhost:port/swagger-ui.html

 

 

위와 같이 Swagger UI가 나타난다.

 

Node.js의 경우엔 스웨거 API 문서를 만들기 위해서는 @swagger 주석을 통해 스웨거라는 것을 표현하고, API에 대한 내용들을 하나하나 모두 작성해야 했다.

https://jamong-icetea.tistory.com/359?category=869906

간단하게 알아보고 사용해보는 swagger!

 

개인적으로 실제 문서화하는 것과 별 차이 없이 비효율적이라고 생각했는데 스프링 스웨거의 경우 문서 작성이 간단했다.

 

 

이는 컴파일 과정의 존재 유무 차이인 것일까?

 

자바는 컴파일하는 과정에서 코드를 읽어들이니 이 컴파일 시점에 어노테이션을 통해 스웨거가 작동해서 자동으로 문서화 작업이 가능한 것 같다.

 

반면 Node.js의 경우 컴파일시점이 없기 때문에 자동으로 문서화 처리하는 과정을 침투시킬 수 없으니 개발자가 하나하나 작성하는게 아닌가 생각된다.

 

그럼 TS로 할 경우 컴파일 과정이 존재하니 TS 컴파일 과정에 수행될 수 있는 스웨거를 만들면...?

 

 

 

 

 

번외. Spring Security 임시 대처 방안

현재 Spring Security를 학습 중인데, 학습 도중 Swagger를 설정해버려서 UI 페이지가 접속이 안되는 문제가 발생했다.

해당 문제는 Spring Security 룰이 작동해서 권한이 없다고 차단했던것;;

 

Spring Security 구성 클래스를 열어보면 WebSecurityConfigurerAdapter 추상 클래스로부터 오버라이딩하는 configure(WebSecurity) 메소드가 있다.

해당 메소드는 Spring Security 룰 예외 규칙으로 작동하는 메소드다.

여기에 swagger에 관련된 주소들을 예외 등록해주면 된다.

/**
* 스프링 시큐리티 룰 예외 규칙
* @author Johnny
*/
@Override
public void configure(WebSecurity web) throws Exception {
    web.ignoring()
        .antMatchers("/css/**", 
            "/js/**", 
            "/img/**", 
            "/lib/**", 
            "/h2-console/**", 
            "/v2/**", // swagger
            "/webjars/**", // swagger
            "/swagger**", // swagger
            "/swagger-resources/**", // swagger
            "/member/**");
}

 

이렇게 예외 등록을 하고 접속하면 정상적으로 접속이 된다.

 

혹은 위의 URI에 대해 permitAll()을 통해 어떠한 유저든 접속하도록 설정해도 된다.

 

근데 뭔가 다른 방법이 있지 않을까...?

 

일단 임시조치다.