코딩 - 문서 자동화 (Spring Boot 2.7.12)

API 문서 작성은 프로젝트의 사용자 및 개발자에게 중요한 정보를 제공하여 API를 쉽게 이해하고 사용할 수 있도록 하는 과정이다. Spring에서는 Swagger(또는 OpenAPI)를 사용하여 API 문서를 자동으로 생성할 수 있다. 기존 환경에 간단한 설정 추가 만으로 RESTful API 문서를 자동으로 생성하여 제공하는 것이 인상적이였다.


◼︎ 환경

• Model : MacBook Pro (14-inch, 2021)
• CPU : Apple M1 Pro
• MENORY : 16GB
• DISK : 512 GB SSD
• OS : macOS 13.2.4 (22F66)
• TOOLS : Visual Studio Code, Java 11, Gradle, Docker
• Version Control : GitHub
• Programming Language : Java
• Framework : Spring Boot 2.7.12, Spring Security 5.7.7
• DBMS : MySql 8.0.33

gradle 기반 spring boot 프로젝트에서 swagger 을 사용하기위해서는 아래와 같은 과정이 필요하다.

1. 의존성 추가
2. Swagger 설정
3. 문서화를 위한 어노테이션 적용 (자동으로 문서를 생성해주지만 가독성을 위하여 어노테이션을 사용하는 것이 좋다)

1. 의존성 추가 

프로젝트의 build.gradle 파일에 Swagger 관련 의존성을 추가한다. Swagger 3.x 버전 부터는 아래와 같이 하나의 의존서만 추가하면 된다.

implementation 'io.springfox:springfox-boot-starter:3.0.0'

2. Swagger 설정 

Spring Security 을 사용하는 경우 브라우져에서 http://localhost:8080/swagger-ui 접속하면 아래와 같은 팝업이 보여진다. (이는 spring security 에서 접근을 제한하여 발생된다)

이경우에는 Security Filter 설정이 추가로 필요하다. WebSecurityConfig (커스텀 설정 파일) 설정 파일에 아래와 같이 swagger 관련 자원에 대한 접속을 허용하도록 한다.

@Configuration

@EnableWebSecurity

@Slf4j

public class WebSecurityConfig {

    @Bean

public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

http

.cors(cors -> cors.configurationSource(corsConfigurationSource()))

.headers((headers) -> headers

.frameOptions().disable())

.authorizeHttpRequests((authz) -> authz

.antMatchers("/swagger-ui/**", "/swagger-resources/**", "/v3/api-docs" ).permitAll()

.anyRequest().authenticated()

)

return http.build();

}

}

3. 프로그램 실행 

브라우져에서 http://localhost:8080/swagger-ui 접속하면 별다른 설정을 하지 않아도 자동으로 문서를 생성하여 보여준다. 가독성을 위하여 문서화 대상 클래스 코드에서 어노테이션을 사용하여 기술을 추가하면 더 쉬운 문서를 만들 수 있다. (참고로 문서화는 REST API 부분만 적용했다)

• 특정 컨트롤러, 함수, 파라메터을 문서에서 제외하려면 @ApiIgnore 어노테이션 사용.

참고자료

• https://springfox.github.io/springfox/docs/current/#getting-started  
• https://velog.io/@banjjoknim/Swagger 
• https://github.com/bezkoder/spring-boot-swagger-3-example