전자정부프레임워크에 Swagger 적용하기

오늘은 전자정부프레임워크 기반 프로젝트에 Swagger를 적용하는 방법에 대해 알아보겠습니다. Swagger는 RESTful API를 시각화하고 문서화하는 도구로, API를 테스트하거나 관리하기 쉽게 만들어줍니다.

---

1. Swagger란?

Swagger는 API 설계를 문서화하고 시각화하여 API 사용을 직관적으로 지원하는 오픈소스 도구입니다. Swagger를 사용하면 다음과 같은 이점을 얻을 수 있습니다:

• API 명세 자동 생성
• API 시각화 및 테스트
• 개발자와 사용자 간 원활한 협업 지원

---

2. Swagger 적용 준비

2-1. 의존성 추가

전자정부프레임워크는 Maven 기반 프로젝트입니다. pom.xml 파일에 Swagger 의존성을 추가합니다.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2-2. Swagger UI 의존성

Swagger UI는 브라우저에서 API 문서를 시각적으로 확인할 수 있도록 도와줍니다. springfox-boot-starter가 포함되어 있으므로 별도 추가는 필요하지 않습니다.

---

3. Swagger 설정 파일 작성

Swagger 설정을 위한 Java Config를 작성합니다.

SwaggerConfig.java

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("전자정부프레임워크 API")
                        .description("전자정부프레임워크 기반 RESTful API 명세")
                        .version("1.0")
                        .build());
    }
}

---

4. Controller에 Swagger 주석 추가

Swagger는 @Api, @ApiOperation, @ApiParam과 같은 어노테이션을 통해 API 설명을 추가할 수 있습니다.

SampleController.java

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(tags = "샘플 API")
public class SampleController {

    @GetMapping("/api/greet/{name}")
    @ApiOperation(value = "인사 API", notes = "사용자 이름을 입력받아 환영 메시지를 반환합니다.")
    public String greet(@ApiParam(value = "사용자 이름", required = true) @PathVariable String name) {
        return "안녕하세요, " + name + "님!";
    }
}

---

5. Swagger UI 실행

5-1. 애플리케이션 실행

애플리케이션을 실행한 후, 브라우저에서 Swagger UI에 접근합니다.

• URL: http://localhost:8080/swagger-ui/index.html

5-2. Swagger UI 화면

Swagger UI에서 API 명세와 테스트가 가능합니다.

• API 목록 확인: 프로젝트에 포함된 모든 RESTful API가 리스트로 표시됩니다.
• API 테스트: 각 API에 입력값을 제공하고 결과를 확인할 수 있습니다.

---

6. 마무리

오늘은 전자정부프레임워크에 Swagger를 적용하여 RESTful API를 문서화하는 방법을 알아보았습니다. Swagger를 통해 API를 직관적으로 관리하고, 테스트 자동화를 활용할 수 있습니다. 다음에는 API 인증 및 보안 설정 방법을 살펴보겠습니다.