오늘은 이클립스와 스프링 기반의 프로젝트에 스웨거를 적용하는 방법에 대해 적어보려 합니다.
전체 프로세스
- Pom.xml 에 의존성 추가(swagger 라이브러리)
- SwaggerConfig.java 생성 (Swagger 관련 설정 담당)
- Dispatcher-Servlet.xml 수정 (Bean 등록 추가)
- Controller 단 수정 (Swagger관련 어노테이션 추가)
- Swagger UI 확인
하나씩 자세히 알아보겠습니다
Pom.xml 에 의존성 추가(swagger 라이브러리)
pom에 관련 라이브러리 2개를 추가합니다.
버전은 2.9.2를 기준으로 작성할게요.
(3.0.0 부터는 상세 설정이 조금씩 달라지니까, 다른 글을 확인 해보세요)
아래를 복사해서 사용하시면 됩니다.
<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>SwaggerConfig.java 생성 (Swagger 관련 설정 담당)
Swagger 관련 설정을 정의할건데, 적당한 위치에 아래 파일을 만들어주세요
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Your API Title")
.description("Your API Description")
.version("1.0.0")
.build();
}
}위의 Docket은 Swagger 문서를 구성하는 데 사용되는 핵심 구성 요소 중 하나입니다. 이 설정은 Swagger가 문서화 할 API의 내용과 대상 패키지를 지정합니다.
DocumentationType.SWAGGER_2: Swagger 버전을 지정합니다.
select(): 문서화 할 API를 선택합니다.
apis(RequestHandlerSelectors.basePackage("com.example.controller")): 문서화 할 API가 포함 된 패키지를 선택합니다. 해당 패키지 내에 있는 모든 클래스가 문서화 대상이 됩니다.
paths(PathSelectors.any()): 문서화 대상 API의 URL을 선택합니다. PathSelectors.any()를 사용하면 모든 URL이 대상이 됩니다. 이것은 대부분의 경우에 유용합니다.
build(): Docket 객체를 생성합니다.
이 설정을 통해 Swagger는"com.example.controller" 패키지에 있는 모든 API를 문서화하고, 모든 URL을 대상으로 문서를 생성합니다.
이를 통해 Swagger UI를 사용하여 문서화 된 API를 쉽게 찾을 수 있습니다.
아래의 apiInfo()는 Swagger UI 페이지에 출력될 API 소개 내용에 대한 설정입니다.
일단 이렇게 설정해서 화면을 만들고, 원하는 문구로 수정하시면 됩니다
Dispatcher-Servlet.xml 수정 (Bean 등록 추가)
bean의 class 속성에는 SwaggerConfig.java 파일에 속한 패키지를 적어주시면 됩니다
<!-- swagger -->
<bean id="swagger2Config" class="com.example.config.SwaggerConfig"></bean>
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"></mvc:resources>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"></mvc:resources>SwaggerConfig 클래스를 swagger2Config 빈으로 등록합니다. SwaggerConfig 클래스는 Swagger 설정을 담당합니다.
mvc:resources를 사용하여 Swagger UI에서 사용할 정적 리소스를 등록합니다.
location 속성은 Swagger UI 리소스가 위치한 경로를 지정하고, mapping 속성은 해당 리소스를 사용할 URL 패턴을 설정합니다.
첫 번째 mvc:resources 요소에서는 swagger-ui.html 파일에 대한 매핑을 설정합니다. Swagger UI는 이 HTML 파일을 통해 브라우저에서 Swagger UI를 표시합니다.
두 번째 mvc:resources 요소에서는 webjars 디렉토리 내에 있는 정적 리소스에 대한 매핑을 설정합니다. 이 디렉토리에는 Swagger UI에서 사용되는 JavaScript, CSS, 이미지 등의 파일이 포함되어 있습니다. /webjars/** URL 패턴은 모든 webjars 디렉토리 내의 파일에 대해 매핑됩니다.
Controller 단 수정 (Swagger관련 어노테이션 추가)
@RestController
@RequestMapping("/test")
@Api(value = "Example API List", tags = "Example API")
public class ExampleController {
@ApiOperation(value = "id로 결과를 조회합니다", notes = "Returns an example by their ID")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "성공"),
@ApiResponse(code = 404, message = "오류")
})
@GetMapping("/examples/{id}")
public Example getExampleById(@PathVariable Long id) {
// 기존 Controller 로직
}
}새롭게 작성이라면 이런식으로 작성을 하시면 되고
추가를 하게 된다면 @Api로 시작 되는 어노테이션을 프로젝트와 기능에 맞게 작성해서 추가해주시면 됩니다.
@ApiOperation 어노테이션을 사용하여 각 엔드포인트에 대한 설명과 메서드를 지정합니다.
@ApiResponses 어노테이션을 사용하여 각 응답 코드에 대한 설명과 메시지를 지정합니다.
마지막으로 테스트는
http://localhost:8080/swagger-ui.html 에 접속해서 UI를 확인합니다.
만약 prefix (context-path)등이 있다면8080 뒤에 /{prefix}를 넣어서 입력해주세요
ㄲㅡㅌ