백엔드 개발자가 API 문서를 일일이 URL 및 Request, Response를 작성해 프론트엔드 개발자에게 전달하는 방식을 사용했다. API 문서를 일일이 작성하므로 생산성이 떨어지고, 문서의 일관성이 떨어지고, API 문서가 변경되면 다시 일일이 변경해줘야 되었다. 잘못 작성할 수 도 있어 효율이 떨어졌다.

→자동 문서화 도구가 나온 이후로 개발자는 직접 문서를 작성하지 않아도 되어서 개발 시간을 단축할 수 있다.

Swagger

Swagger UI를 사용해 API 쉽게 테스트 할 수 있다.

API 호출 시 전달해야 할 파라미터를 확인할 수 있다.

API 버전 관리가 용이해진다.

사용방법

1. yaml 파일

• Swagger UI를 위한 서버를 따로 두고 Swagger에서 API 요청을 하면 그 요청을 해당 서버로 전달

이 방법은 api 서버와 Swagger UI를 별도로 배포 및 관리하고자 하는 경우에 적합하다. 관리 비용이 더 들고 , 애플리케이션 간의 동기화를 고려해야 하는 등 주의가 필요하다.

2. 소스 코드 내에서 Swagger를 설정하여 구성하는 방법

• spring framework에서 구성한다면, 서버 자체가 Swagger 겸 백엔드 서버가 돼서 요청 및 응답을 처리하게 된다.

  

@GetMapping("/{memberId}") @Operation(summary = "Get member profile") @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "성공", content = {@Content(schema = @Schema(implementation = MemberProfileRes.class))}), @ApiResponse(responseCode = "404", description = "해당 ID의 유저가 존재하지 않습니다."), }) public MemberProfileRes getMemberProfile( @PathVariable @Positive(message = "유저 ID는 양수입니다.") @Schema(description = "Member ID", example = "1") Long memberId,

// TODO: Replace with member ID from JWT or that from any other authentication method
@Parameter(name = "loginId", description = "로그인 유저 ID 값", example = "3", required = true)
@Positive(message = "유저 ID는 양수입니다.") @RequestParam final Long loginId