스프링 부트를 활용한 RESTful API 개발과 문서화 방법

스프링 부트를 활용한 RESTful API 개발

스프링 부트는 경량화된 스프링 프레임워크로, 내장형 서버와 자동설정 기능 등을 제공하여 빠르고 쉽게 웹 애플리케이션 개발이 가능합니다. 스프링 부트를 이용하여 RESTful API를 개발하는 방법에 대해 알아보겠습니다.

RESTful API란?

REST는 Representational State Transfer의 약자로, HTTP/1.1 프로토콜을 기반으로 클라이언트와 서버 간의 통신 방식을 정의한 아키텍처입니다. RESTful API는 이러한 REST 아키텍처를 따르는 API를 의미합니다. RESTful API는 자원(URI)과 HTTP 메서드(GET, POST, PUT, DELETE)를 이용하여 데이터를 주고받습니다.

스프링 부트를 이용한 RESTful API 개발 과정

1. 스프링 부트 프로젝트 생성

먼저, 스프링 부트 프로젝트를 생성합니다. 스프링 부트는 스프링 이니셜라이저를 통해 쉽게 프로젝트를 생성할 수 있습니다. 스프링 이니셜라이저는 웹 애플리케이션, 데이터베이스, 보안 등 다양한 기능을 선택할 수 있는 옵션을 제공합니다.

$ curl https://start.spring.io/starter.zip -d dependencies=web -d language=java -d javaVersion=11 -o demo.zip
$ unzip demo.zip

2. 의존성 추가

RESTful API를 개발하기 위해 스프링 부트에서는 Spring Web Starter를 사용합니다. Spring Web Starter는 웹 애플리케이션 개발에 필요한 의존성을 제공합니다.


    org.springframework.boot
    spring-boot-starter-web

3. Controller 작성

Controller는 클라이언트의 요청을 처리하고 응답을 반환하는 역할을 합니다. 스프링에서는 @RestController 어노테이션을 사용하여 Controller를 작성합니다.

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, world!";
    }
}

위 코드는 /hello 경로로 GET 요청이 들어오면 "Hello, world!"를 반환하는 Controller입니다.

4. 빌드 및 실행

프로젝트를 빌드하고 실행합니다.

$ mvn package
$ java -jar target/demo-0.0.1-SNAPSHOT.jar

5. API 테스트

API를 테스트하기 위해 웹 브라우저나 API 클라이언트를 사용할 수 있습니다. 웹 브라우저에서는 http://localhost:8080/hello 경로로 접속하여 결과를 확인할 수 있습니다. API 클라이언트를 사용할 경우, GET 메서드로 http://localhost:8080/hello 경로에 요청을 보내면 "Hello, world!"가 반환됩니다.

API 문서화를 위한 스프링 부트 설정 방법

RESTful API를 개발한 후 API의 사용 방법을 문서화하는 것은 매우 중요합니다. Swagger를 이용하여 스프링 부트에서 API 문서화를 쉽게 할 수 있습니다.

Swagger란?

Swagger는 RESTful API를 문서화하고 테스트할 수 있는 도구입니다. Swagger는 API의 경로, 매개변수, 응답값 등을 기술한 YAML 파일을 이용하여 API 문서를 생성합니다.

Swagger 의존성 추가

Swagger를 사용하기 위해서는 다음 의존성을 추가해야 합니다.


    io.springfox
    springfox-boot-starter
    3.0.0

Swagger 설정

Swagger 설정은 스프링 부트의 설정 파일(application.yml 또는 application.properties)에 작성합니다. 다음은 Swagger 설정에 대한 예시입니다.

springfox:
  documentation:
    swagger-ui:
      enabled: true
  swagger-ui:
    path: /swagger-ui.html
    resources:
      swagger:
        enabled: true

Swagger UI를 활용한 API 문서화 방법

Swagger UI를 이용하여 API 문서를 생성할 수 있습니다. Swagger UI는 Swagger에서 생성한 YAML 파일을 이용하여 API 문서를 렌더링합니다.

1. Swagger UI 의존성 추가

Swagger UI를 사용하기 위해서는 다음 의존성을 추가해야 합니다.


    org.webjars
    swagger-ui
    3.51.1

2. Swagger 설정

Swagger 설정은 스프링 부트의 설정 파일(application.yml 또는 application.properties)에 작성합니다. 다음은 Swagger 설정에 대한 예시입니다.

springfox:
  documentation:
    swagger-ui:
      enabled: true
  swagger-ui:
    path: /swagger-ui.html
    resources:
      swagger:
        enabled: true

3. Swagger UI 사용

Swagger UI를 사용하기 위해, http://localhost:8080/swagger-ui.html 경로로 접속합니다. Swagger UI에서는 API의 목록, 매개변수, 응답값 등을 확인할 수 있습니다.

스프링 부트와 Swagger UI를 활용한 API 문서화 예제

다음은 Swagger를 이용하여 API를 문서화한 예시입니다.

@RestController
@Api(tags = "Hello", description = "인사 API")
public class HelloController {
    @ApiOperation(value = "Hello, world!", notes = "간단한 인사말을 반환합니다.")
    @GetMapping("/hello")
    public String hello() {
        return "Hello, world!";
    }
}

위 코드는 /hello 경로로 GET 요청이 들어오면 "Hello, world!"를 반환하는 Controller입니다. @Api 어노테이션을 이용하여 API의 정보를 기술하고, @ApiOperation 어노테이션을 이용하여 API의 설명을 작성합니다.

Swagger UI에서는 다음과 같이 API를 확인할 수 있습니다.

Swagger UI

결론

이번 글에서는 스프링 부트를 이용하여 RESTful API를 개발하고, Swagger를 이용하여 API를 문서화하는 방법에 대해 알아보았습니다. RESTful API를 개발하고 문서화하는 것은 매우 중요한 일이며, 스프링 부트와 Swagger를 이용하면 쉽고 빠르게 API를 개발하고 문서화할 수 있습니다.