안녕하십니까.
이번 포스팅에서는 Spring Boot에 Swagger API를 붙이는 방법에 대하여 알아 보려고 합니다.
gradle 설정
gradle을 사용하실 경우 아래의 한줄을 build.gradle의 dependency에 추가해 줍니다.
implementation 'io.springfox:springfox-swagger2:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0' |
Maven 설정
Maven을 사용하실 경우 아래의 설정을 추가하시면 됩니다.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency> |
설정 파일 추가
gradle, maven을 통하여 코드를 불러오셨으면, 이에 따라 swagger 설정을 해야합니다.
다음과 같이 파일을 하나 생성하며 @Bean으로 등록해 주시면 됩니다. 코드는 간단하게 모든 api에 대하여 스웨거를 빌드한다는 내용 입니다.
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket swaggerApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
} |
실행
바로 스프링 빌드를 해주시고 실행해주시면 됩니다. 저는 아래와 같이 API들을 확인할 수 있었습니다.
문서화 하기
스웨거는 테스팅 툴이기 동시에 문서화 툴이기도 합니다. 파라미터에 설명을 넣어주지 않으면 아래와 같이 단순하게 파라미터가 설정이 되는데요. 이를 위해서는 코드에 기입해주어야 합니다.
메소드 문서화
다음과 같이 @ApiOperation 어노테이션을 통해서 Method에 설명을 넣을 수 있습니다.
@GetMapping("/detail")
@ApiOperation(value="포트폴리오 디테일 ", notes="디테일 뷰를 리턴해준다.")
public String detail(Model model, @RequestParam(value = "name", required = false) String name) {
model.addAttribute("details", portfolioService.getDetail(name));
model.addAttribute("name", name);
return "portfolio/detail";
}
|
위의 빈을 넣으시면 아래와 같이 설명이 추가 됩니다.
DTO 문서화
DTO도 문서화해야할 필요성이 있는데요. 아래와 같이 @ApiModelProperty를 통해서 처리할 수 있습니다.
public class PortfolioDetailDTO { @ApiModelProperty(example = "포트폴리오 타입 이름.") public String name; } |
위처럼 넣을 경우 다음과 같이 추가가 됩니다.
전달하는 파라미터의 주석도 필요할 수 있습니다.
@GetMapping("/detail") @ApiOperation(value = "포트폴리오 디테일 ", notes = "디테일 뷰를 리턴해준다.") public String detail(Model model, @RequestParam(value = "name", required = false) @ApiParam(value = "name", example = "이름") String name) { model.addAttribute("details", portfolioService.getDetail(name)); model.addAttribute("name", name); return "portfolio/detail"; } |
API 테스트 하기
테스트 하는 법은 간단합니다. 다음과 같이 파라미터에 값을 넣어주시고 Try it out! 버튼을 클릭하시면 바로 테스트가 가능 합니다.
댓글
댓글 쓰기