Swagger 사용하기

Spring 프로젝트를 진행하는데 api 문서를 정리해서 제출해야하는 상황이 생겼다. 

기존에는 Postman 화면을 일일히 캡쳐하여 정리하곤 했는데 이때 한 팀원 분께서 swagger 를 이용하여 문서 정리를 하자고 하셔서 swagger에 대해서 알아보게 되었다!

 

Swagger란?

개발한 Rest API를 편리하게 문서화 해주고, 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트

=> 스웨거는 Web API 문서화를 위한 도구

 

2가지 종류의 라이브러리

• Spring-Fox
  • 오래전에 나온 라이브러리 이다.
  • 2020년 이후로 업데이트가 없다.
• Spring-Doc
  • 2019년에 나온 라이브러리 이다.
  • 꾸준하게 업데이트가 되고 있다. 

위 두 종류 중에서 우리는 Spring-Doc 을 사용하게 되었다.

 

적용방법(진행한 프로젝트 예시)

// 프로젝트 스펙

-자바 jdk: 17

- 스프링: 3.x.x 버전 사용

- 프로젝트 db : rds 사용

build.gradle 에 라이브러리 추가해주기

//build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.3'

application.yml

springdoc:
  api-docs:
    path: /v1/api-docs
    groups:
      enabled: true
  packages-to-scan: **스캔할 패키지 적기**
  swagger-ui:
    tags-sorter: alpha
    groups-order: asc
    syntax-highlight:
      activated: true
    try-it-out-enabled: false

 

API 개발 후 어노테이션 작성

@Tag : api 그룹 설정

Target: ANNOTATION_TYPE, METHOD, TYPE

• name: 태그의 이름
• description: 태그에 대한 설명

Tag에 설정된 name이 같은 것 끼리 하나의 api 그룹으로 묶는다. 주로 Controller나 Controller의 Method 영역에 설정한다고 한다.

 

@Operation: api 상세 정보 설정

Target: ANNOTATION_TYPE, METHOD

• summary: api에 대한 간략한 설명
• description: api에 대한 상세 설명
• response: api Response 리스트
• parameters: api 파라미터 리스트

@Operation어노테이션은 api동작에 대한 명세를 작성하기 위해 Controller 메소드에 설정한다.

Swagger UI가 fold상태일때도 간략히 확인할 수 있는 간략정보는 summary에 작성하고, 필요에 따라 상세 정보를 표기하고자 한다면 description에 설명을 추가하면 된다.

 

@ApiResponse: api response 설정 

Target: ANNOTATION_TYPE, METHOD, TYPE

• responseCode: http 상태코드
• description: response에 대한 설명
• content: Response payload 구조
  • schema: payload에서 이용하는 Schema
    • hidden: Schema 숨김 여부
    • implementation: Schema 대상 클래스

@ApiResponse 는 응답 결과에 따른 response 구조를 미리 확인할 수 있게 해준다.

만약 @ApiResponse를 지정하지 않으면 아래 이미지처럼 Swagger UI에서는 상태코드 200과 비어있는 response body를 보여준다.

 

@Schema : api Schema 설정

Target : ANNOTATION_TYPE, FIELD, METHOD, PARAMETER, TYPE

• description : 한글명
• defaultValue : 기본값

Schemea(= Model)에 대한 정보를 작성

 

- Controller

@Tag(name = "여정 API", description = "여정 관련 API 모음입니다.")
@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/itinerary")
public class ItineraryController {

    private final ItineraryService itineraryService;

    @Operation(summary = "여정 생성 API", description = "여정 생성 API 입니다.")
    @ApiResponse(responseCode = "200", description = "생성 성공시", content = @Content(schema = @Schema(implementation = ItineraryCreateResponse.class)))
    @FailApiResponses
    @PostMapping("")
    public ResponseEntity<ItineraryCreateResponse> create(
            @RequestParam Long tripId,
            @Valid @RequestBody ItineraryCreateRequest request
    ) {
        ItineraryCreateResponse response = itineraryService.create(tripId, request);

        return ResponseEntity.ok(response);
    }
    ...

 

requestDTO

public class ItineraryCreateRequest {
    @Schema(description = "여정 명", defaultValue = "생성할 여정 이름")
    @NotBlank
    private String itineraryName;
    @Schema(description = "이동 수단", defaultValue = "생성할 이동수단")
    @NotBlank
    private String transportation;
    @Schema(description = "출발지", defaultValue = "생성할 출발지")
    @NotBlank
    private String departCity;
    @Schema(description = "도착지", defaultValue = "생성할 도착지")
    @NotBlank
    private String arriveCity;
    @Schema(description = "출발 일시", defaultValue = "2023-10-25T10:00:00")
    @NotNull
    private LocalDateTime cityDepartTime;
    @Schema(description = "도착 일시", defaultValue = "2023-10-25T12:00:00")
    @NotNull
    private LocalDateTime cityArriveTime;
    ...

 

Swagger 화면

서버를 올린후에 http://localhost:8080/swagger-ui/index.html 주소로 들어가면 아래와 같이 잘 정리된 문서를 볼 수 있다

 

스웨거 ? 짱 편한거같다 굳굳

프로젝트 진행할때 어디에 어떤 API 가 있는지, 어떻게 사용해야 하는지를 한눈에 볼 수 있어서 자주 사용하게 될 것 같다!

참고자료

https://www.baeldung.com/spring-rest-openapi-documentation