Swagger로 API 문서 자동화: 실습 후기와 튜토리얼

 

 

 

 

 

안녕하세요 

 

오늘은 swagger를 사용해서 api 문서를 자동화하는 것을 실습을 통해 알아보겠습니다.

 

 

1. 제 쇼핑몰 개인프로젝트에 적용시키려 합니다.

 

먼저 제 스프링 부트 버전과 자바 버전입니다. 

 

버전을 보여드리는 이유는 스프링부트 2.6 이상부터 적용해야하는 것이 있기 때문입니다.

 

 

 

 

2. 제가 사용한 의존성입니다.

 

 

 

3. SwaggerConfig 작성

 

 

@EnableOpenApi 는 버전에 따라 변할 수 있습니다.

 

문서 타입도 버전에 따라 가장 적당한것을 써주시면 됩니다.

 

베이스패키지에는 api를 문서화할 컨트롤러가 들어가 주면 됩니다.

 

경로는 /api.* api로 시작하는 모든 api들입니다.

 

 

4. 컨트롤러에 api 설명 추가

 

@Slf4j
@RestController
@RequestMapping("/api")
@CrossOrigin("*")
@Api(value = "Cart Controller", description = "장바구니 관련된 API")
public class CartController {
    private final CartService cartService;

    @Autowired
    public CartController(CartService cartService)
    {
        this.cartService = cartService;
    }

    @Data
    public static class RegiCartReq {
        String userEmail;
        Long pdNo;
        int quantity;
    }

    @Data
    public static class UpdateCartReq {
        Long cartId;

        int quantity;
    }

    // 장바구니 생성
    @PostMapping("/cart/create")
    @ApiOperation(value = "장바구니 생성", notes = "장바구니를 생성합니다.")
    public ResponseEntity<Cart> addToCart(@RequestBody RegiCartReq regiCartReq) {

        return ResponseEntity.ok(cartService.addToCart(regiCartReq.getUserEmail(), regiCartReq.getPdNo(), regiCartReq.getQuantity()));
    }

    // 장바구니 전체 조회
    @GetMapping("/cart/{userEmail}")
    @ApiOperation(value = "장바구니 전체 조회", notes = "유저의 장바구니를 조회합니다.")
    public ResponseEntity<List<Cart>> getCartsByUserId(@ApiParam(value = "장바구니 전체 조회 하려는 userEmail", required = true) @PathVariable("userEmail") String userEmail) {
        return ResponseEntity.ok(cartService.getCartsByUserId(userEmail));
    }

    // 장바구니 수량 업뎃 (cartId 이용하면 될듯)
    @PutMapping("/cart/update")
    @ApiOperation(value = "장바구니 수량 업데이트", notes = "유저의 장바구니를 상품을 업데이트 합니다.")
    public ResponseEntity<Cart> updateCart(@RequestBody UpdateCartReq updateCartReq) {
        return ResponseEntity.ok(cartService.updateCart(updateCartReq.getCartId(), updateCartReq.getQuantity()));
    }

    // 장바구니 삭제
    @DeleteMapping("/cart/{cartId}")
    @ApiOperation(value = "장바구니 삭제", notes = "유저의 장바구니를 삭제합니다.")
    public ResponseEntity<Void> deleteCart(@ApiParam(value = "장바구니 삭제 하려는 cartId", required = true) @PathVariable("cartId") Long cartId) {
        cartService.deleteCart(cartId);
        return ResponseEntity.noContent().build();
    }
}

 

저의 장바구니 컨트롤러에 swagger를 적용시킨 모습입니다.

 

@Api , @ApiOperation, @ApiParm 등 swagger에서 지원하는 다양한 기능들을 적용해보세요

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

 

 

 

5. yml 설정

 

아까 처음에 스프링 부트 2.6 버전 이상부터는 application.yml에 해당 설정을 해주세요

 

해당 설정을 하지 않으시면 기본 설정된 전략으로 인해 swagger에서 error가 발생하게 됩니다.

 

 

 

 

6. 이제 로컬에서 실행해 봅시다.

 

http://localhost:8000/swagger-ui/index.html

여기로 들어가 줍니다.

 

 

 

저의 api들이 아주 아름답게 문서화 되어있습니다.

 

각각의 api들을 눌러보시면 postman처럼 api 요청도 해보실 수 있습니다.

 

좀더 다양한 기능은 공식문서를 확인해 보세요.

 

감사합니다.