Swagger UI
Swagger API
Swaggeer 구현
배포하기 전 프론트엔드 동료들과 좀 더 원활하게 소통하기 위해 Swagger로 API 문서를 만들어서 공유하기로 했습니다.
처음 적용해보는 기능이라 생소했지만, 생각보다 간단해서 개발 도구의 편리함을 느낄 수 있었습니다.
dependencies 추가
implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'application.yml 추가
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
springfox:
documentation:
swagger-ui:
host: localhost:8080SwaggerConfig 구현(설정 담당)
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.BE.cocktail"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("cocktail API")
.description("API Documentation for cocktail")
.version("1.0.0")
.build();
}
}@Configuration을 사용하여 빈을 주입하여 스프링 컨테이너에서 관리하도록 했습니다.
@EnableSwagger2어노테이션은 Swagger 2.0 버전을 활성화하는 데 사용됩니다. 해당 어노테이션을 통해 스프링 부트에서 Swagger를 사용할 수 있게 했습니다.
Docket은 Swagger API 문서를 생성하는데 사용되는 핵심 클래스인데, DocumentationType.SWAGGER_2를 사용하여 Swagger 2.0 스펙을 사용하도록 설정했습니다.
그리고 select() 메서드로 조건을 설정하는데, 여기서 중요한게 RequestHandlerSelectors.basePackage("com.BE.cocktail") 이 부분입니다. 해당 코드는 특정 패키지에 있는 컨트롤러 클래스만 문서화하도록 지정하는 것 입니다.
그림과 프로젝트에 적용한 코드를 보면 패키지 위치에 맞게 넣어준 것을 확인할 수 있습니다.
그리고 아래에 있는 ApiInfo는 Swagger 문서에 표시되는 API에 대한 정보를 설정하는데, 직관적인 코드 그대로 title()은 문서 제목이고 description()은 문서에 대한 설명입니다.
Swagger - Controller에 적용
코드가 중복이 많아서, 간단하게 정규 레시피 상세 조회 API로 설명드리겠습니다.
@RestController
@RequiredArgsConstructor
@Api(tags = "regularRecipe", description = "정규 레시피 API")
@RequestMapping("/regular")
public class RegularRecipeController {
private final RegularRecipeService regularRecipeService;
@ApiOperation(value = "정규 레시피 상세 조회", notes = "정규 레시피 상세 조회 API")
@ApiImplicitParam(name = "recipe_id", value = "정규 레시피 아이디")
@GetMapping("/find/{recipe_id}")
public ApiResponse<RegularRecipeGetResponseDto> findDetailInfo(@PathVariable("recipe_id") Long id) {
return ApiResponse.ok(regularRecipeService.find(id));
}
}먼저 클래스 레벨에 @Api(tags = "regularRecipe", description = "정규 레시피 API")라고 등록을 해줬는데, @Api()는 Swagger 프레임워크에서 제공되는데, API 문서에 대한 메타 데이터를 제공합니다.
그림을 보면서 설명하면, tags 같은 경우는 🟥 색에 위치하는 곳에 보여지고, description 은 🟦 색에 위치하게 됩니다.
그럼 메서드 레벨에 설정한 어노테이션을 설명하겠습니다.
@ApiOperation(value = "정규 레시피 상세 조회", notes = "정규 레시피 상세 조회 API")를 먼저 보면,
@ApiOperation 는 대상 API의 설명을 작성하기 위한 어노테이션입니다.
정규 레시피 API를 열면 보이는 부분인데 그림으로 설명하겠습니다.
먼저 value에 작성한 것은 🟥 색에 위치하고, notes는 🟦 색에 보여집니다.
다음은 @ApiImplicitParam(name = "recipe_id", value = "정규 레시피 아이디")에 대해 설명드리겠습니다.
@ApiImplicitParam는 매개 변수에 대한 세부 정보를 설명하기 위해 사용합니다.
name은 🟥 색에 위치하고, value는 🟦 색에 보여집니다.
다음은 Dto 클래스를 살펴보겠습니다.
Swagger - Dto 적용
@Getter
@AllArgsConstructor(access = AccessLevel.PRIVATE)
public class RegularRecipeGetResponseDto {
@ApiModelProperty(example = "정규 레시피 아이디")
private Long id;
@ApiModelProperty(example = "칵테일 이름")
private String name;
@ApiModelProperty(example = "칵테일 재료")
private String ingredient;
@ApiModelProperty(example = "칵테일 설명")
private String description;
@ApiModelProperty(example = "칵테일 레시피")
private String recipe;
@ApiModelProperty(example = "칵테일 이미지 URL")
private String imageUrl;
@ApiModelProperty(example = "칵테일 찜 여부")
private boolean wishList;
}@ApiModelProperty 어노테이션을 사용하여 Swagger 문서화를 위한 정보를 제공하는데, 해당 어노테이션은 각 필드에 대한 설명과 예시를 제공해줍니다. 즉, API 사용자에게 API 응답 객체의 의미를 설명하는 것 입니다.
그림을 보면 바로 알 수 있는데, API 문서에서 코드에 적용한 exaple그대로 응답 객체를 설명해줍니다.
통신 테스트
Swagger는 API 명세 관리 뿐만 아니라 직접 통신도 기능도 제공하여 알딸딸 프로젝트 진행 중에 편리하게 이용할 수 있었습니다.
dml.sql 파일에 만들어 놓은 데이터로 정규 레시피 전체 조회 API를 통해 통신테스트를 설명드리면,
Tryitout 버튼을 통해 입력 값을 넣고, 테스트를 할 수 있습니다.
(1)번을 통해 입력 값을 넣으면, (2)번에 데이터 값이 나오는 것을 확인할 수 있습니다.
Last updated