[java] Java Jersey에서 Swagger와 함께 문서화하는 방법은?

29 Nov 2023

java

Java Jersey는 RESTful 웹 서비스를 빌드하기 위해 널리 사용되는 프레임워크입니다. 이 프레임워크를 사용하여 개발된 API를 문서화하는 것은 매우 중요합니다. 이를 위해 Swagger를 사용할 수 있습니다. Swagger는 API를 설명하는 문서를 생성하고, 클라이언트 개발자가 쉽게 API를 이해하고 사용할 수 있도록 도와줍니다.

Swagger를 Java Jersey 프로젝트에 적용하기 위해서는 다음 단계를 따르면 됩니다:

단계 1: Maven 종속성 추가

먼저 Maven 프로젝트의 pom.xml 파일에 Swagger 관련 종속성을 추가해야 합니다. 아래 코드를 <dependencies> 섹션에 추가하세요.

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-jersey2-jaxrs</artifactId>
  <version>2.1.5</version>
</dependency>

단계 2: Swagger 설정 추가

다음으로, Java 프로젝트의 Application 클래스에 Swagger 설정을 추가해야 합니다. 다음과 같이 SwaggerConfig.java 파일을 생성하고 다음 코드를 추가하세요.

import io.swagger.jaxrs.config.BeanConfig;

public class SwaggerConfig {
    public void configureSwagger() {
        // Swagger 설정 초기화
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0.0");
        beanConfig.setSchemes(new String[]{"http", "https"});
        beanConfig.setBasePath("/api");
        beanConfig.setResourcePackage("your.package.name");
        beanConfig.setTitle("Your API Title");
        beanConfig.setDescription("Your API Description");

        // Swagger 설정 스캔
        beanConfig.setScan(true);
    }
}

위의 코드에서 your.package.name은 Java Jersey API가 위치한 패키지 이름으로 수정해야 합니다.

단계 3: Swagger 리소스 등록

마지막으로, Application 클래스에 Swagger 리소스를 등록해야 합니다. 이를 위해 SwaggerResource.java 파일을 생성하고 다음 코드를 추가하세요.

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import io.swagger.annotations.Api;

@Path("/swagger.json")
@Api("/swagger.json")
public class SwaggerResource {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public String getSwaggerJson() {
        return new SwaggerConfig().configureSwagger().toString();
    }
}

단계 4: 서버 시작

이제 Java Jersey 서버를 시작하고 브라우저에서 http://localhost:8080/api/swagger.json 주소로 접속하면 Swagger 문서가 표시됩니다. 이 문서는 API 엔드포인트, 매개변수, 응답 및 예제와 같은 중요한 정보를 표시합니다.

위의 단계를 따르면 Java Jersey에서 Swagger를 통해 API를 문서화할 수 있습니다. 이를 통해 개발자들은 API를 쉽게 이해하고 사용할 수 있으며, 클라이언트 개발에 필요한 작업을 줄일 수 있습니다.

참고 자료

Java Jersey with Swagger