멋사 Backend 89일차 🦁

신재원·2023년 8월 30일

Backend 멋쟁이사자처럼

멋쟁이사자처럼 BackEnd

목록 보기

87/96

API 문서화

API 테스트 팀 워크스페이스로 PostMan 을 사용하고 있었지만,
PostMan 도구는 API 테스트에 중점이 되어있고 팀 워크스페이스 기간이 2일 남은 관계로 swagger 를 도입 하여 API를 문서화 하기로 하였습니다.
팀원들과의 회의에서 postman 도 API 문서화 기능을 제공한다고 했지만, 사람들이 많이 사용하는 swagger 라는 도구를 사용해보면 좋을것 같아 도입 하였습니다.

🙂 swagger 란?

API 문서 생성, 관리 및 시각화 도구로서, 개발자가 RESTful API 를 쉽게 문서화하고 테스트하며 이해할 수 있게 돕는 오픈 소스 프레임워크입니다.
(Java 에 종속된 라이브러리가 아닙니다.)

swagger 사용

swagger 를 사용하는데 앞서 spinrg doc 방식과 spring fox 방식이 있다고 합니다.

spring fox

spring doc 방식보다 일찍 등장하였으며, 2020년 7월의 업데이트를 마지막으로 버전이 업데이트 되지 않았습니다.

spring doc

spring doc 의 업데이트가 중지된 이후로 등장하였으며,
최근까지 (2023 2월) 버전이 업데이트 되어있으며, 늦게 등장한 만큼
spring doc 보다 사용하기 쉬웠습니다.
(다양한 swagger ui 관련 어노테이션 제공)
(@Tag, @Operation 등등 되게 많다)

필자는 이러한 이유로 spring doc 방식을 선택하였으며, swagger 사용하기에 앞서 의존성 추가와 yml (properties) 설정을 해줘야 합니다.

dependencies {

// 다른 의존성....

implementation('org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4')

}

yml 설정

사용할 패키지 경로와, path 정도 수정해서 사용하면 될 것 같습니다.
패키지에 들어있는 @RestController 어노테이션이 있는 클래스가
swagger UI 에 보여지게 되는것 같습니다.

spring:
  # 필수 
  # spirng 2.6 이상 swagger3 부터 매칭 전략을 수정
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

# springdoc, swagger3 설정
springdoc:
  packages-to-scan: com.example.mypetlife.controller # 패키지 경로
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path: / # swagger ui 에 접속할 경로 
    disable-swagger-default-url: true
    display-request-duration: true
    operations-sorter: alpha