많은 경우 자바로 작성된 RESTful API 서버는 스웨거(Swagger)를 사용하여 API 문서를 자동으로 생성합니다. 스웨거를 사용하면 API 엔드포인트, 요청 및 응답 형식 등을 문서화할 수 있습니다. 이를 통해 API를 사용하는 클라이언트나 다른 개발자들이 API를 쉽게 이해하고 사용할 수 있습니다.

스웨거 라이브러리 추가하기

첫 번째로 해야 할 일은 프로젝트에 스웨거 라이브러리를 추가하는 것입니다. 보통 Maven이나 Gradle과 같은 의존성 관리 도구를 통해 다음과 같이 스웨거 라이브러리를 추가합니다.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

스웨거 설정하기

다음으로는 스웨거 설정을 해야 합니다. 스웨거 설정을 위해 @EnableSwagger2 어노테이션을 사용하여 스웨거를 활성화하고, 스웨거 설정 정보를 설정해야 합니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
          .select()
          .apis(RequestHandlerSelectors.basePackage("com.example.controllers"))
          .paths(PathSelectors.any())
          .build();
    }
}

위의 예제에서는 com.example.controllers 패키지 내의 모든 컨트롤러들을 문서에 포함시키도록 설정하였습니다.

스웨거 UI 접속하기

위의 설정이 완료되면 톰캣 서버를 시작하고, http://localhost:8080/swagger-ui.html로 접속하면 스웨거 UI를 볼 수 있습니다. 여기서는 API 엔드포인트들을 확인하고 테스트해볼 수 있습니다.

마치며

스웨거를 사용하여 자바 서버의 API를 문서화하면 API 사용자들이 더 쉽게 API를 사용하고 이해할 수 있습니다. 문서화된 API는 실제로 API를 사용할 때 발생할 수 있는 혼란과 오류를 줄여줄 수 있습니다.

참고 자료:

• Springfox Documentation
• Swagger Official Website