백엔드 개발자가 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
Plain Text
복사
) {
return memberMapper.toResponse(
memberService.findProfileByMemberId(memberId, loginId)
);
}
@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
) {
return memberMapper.toResponse(
memberService.findProfileByMemberId(memberId, loginId)
);
}
Elixir
복사
@Operation: 해당 API의 작업에 대한 간단한 요약을 제공합니다.
@ApiResponses와 @ApiResponse: API 응답에 대한 정보를 제공합니다. 각각의 응답 코드와 그에 해당하는 설명을 제공하며, 특정 응답에 대한 데이터 모델을 지정할 수 있습니다.
@Content와 @Schema: 응답이나 요청에서 사용되는 데이터 모델을 설명합니다. 이를 통해 Swagger UI에서 해당 데이터 모델의 예시와 스키마를 보여줍니다.
@Parameter: API의 파라미터에 대한 정보를 제공합니다. 이를 통해 Swagger UI에서 해당 파라미터의 설명, 예시 등을 보여줍니다.
JDK가 패키지로 제공해주는 JavaDoc을 이용하면 API의 설명, 매개변수, 반환형 등의 메타 데이터를 기술할 수 있다.
/**
* 유저 정보 수정 API.
*
* @param memberId 수정할 유저의 ID
* @param request 수정할 유저 정보
*/
@PutMapping("/me")
public void updateMyProfile(
// TODO: Replace with member ID from JWT or that from any other authentication method
@RequestParam Long memberId,
@RequestBody @Valid MemberProfileUpdateReq request
) {
memberService.updateMyProfile(memberId, memberMapper.toDTO(request));
}
Elixir
복사
/**
•
유저 정보 수정 API.
•
@param memberId 수정할 유저의 ID
•
@param request 수정할 유저 정보
*/
@PutMapping("/me")
public void updateMyProfile(
// TODO: Replace with member ID from JWT or that from any other authentication method
@RequestParam Long memberId,
@RequestBody @Valid MemberProfileUpdateReq request
) {
memberService.updateMyProfile(memberId, memberMapper.toDTO(request));
}
Spring REST Docs
Spring REST Docs는 스프링 프레임워크에서 제공하는 API 문서 자동화 도구이다. Spring REST docs는 스웨거와 다르게 프로덕션 코드에 문서화를 위한 별도의 코드를 추가하지 않아도 된다.
테스트 코드를 작성하며 API를 명세할 수 있다. 미리 정의한 테스트(스프링 통합 테스트 혹은 컨트롤러 슬라이스 테스트)가 실행되고 해당 테스트가 성공하면, 그 테스트에 대한 asciidoc 스니펫이 생성된다.
이 스니펫과 손으로 직접 작성한 문서를 결합하여 최종적인 API 문서를 완성하면 된다.
테스트코드를 기반으로 문서가 생성되다보니 테스트가 성공하는 올바른 프로덕션 코드에 대해서만 문서를 작성할 수 있다. 테스트가 실패하면, 문서를 생성할 수 없다. 그로 인해서 스웨거와는 다르게 API 스펙과 항상 일치하는 문서를 작성할 수 있다.
