(1) restdocs + openapi3 + swagger-ui 설정을 해보자 - 설명편

 

서론

  보통 현재 다니고 있는 부트캠프에서 저는 백엔드 포지션으로 개발할 때 프론트엔드와 작업할 때 다음과 같은 순서로 API를 맞춰나갔습니다.

1. 노션으로 처음에 싱크업을 하고,
2. FastAPI(BE)나 MSW(FE)같은 툴을 이용한 Mock 서버 구성을 하여 개발 속도를 맞춘 다음
3. RestDocs나  Swagger같은 API 문서 자동화 툴을 이용하여 API 문서를 작성

노션으로 작업한 API 문서(회원 도메인 부분 캡쳐)

 

  프론트엔드와 협업을 위한 API 문서를 작성할 때 노션에 API 문서를 위와 같은 형태로 많이 작성하곤 했습니다. 노션을 선택했던 이유는 보편화가 많이 되기도 했고, 실시간 작업이 가능하며, UI가 마크다운이어서 가독성이 좋고 편집하기도 좋았으며 액셀만큼은 아니지만 표와 데이터베이스 같이 데이터를 관리하기에 편리하다는 장점들이 있어서였습니다. 또, 문서를 다음과 같이 보기 좋게 JSON 형식의 코드도 첨부할 수도 있었구요.

노션으로 작업한 API 문서의 요청-응답 페이지(회원 로그인 예시)

  위 문서로 대충 어떤 데이터를 요청을 보내고, 어떤 데이터가 응답이 온다는 것을 적은 다음, 문서 자동화를 본격적으로 시작했었습니다.

 

Swagger

스프링의 펫스토어 앱 예시

 

  보통 API 문서화를 하는 데 Swagger를 옛날부터 많이 사용하고 있습니다. 위 스크린샷처럼 알록달록하게 HTTP 메소드와 URL을 표시하는게 큰 특징이고, 직접 URL을 테스트해볼 수도 있다는 것이 특징입니다. 하지만 개발 중인 컨트롤러의 소스코드에 직접 주석을 달아줘야 한다는게 제일 큰 단점이었죠. 아래와 같이 코드에 어쩔 수 없이 내용이 많아져서 가독성이 낮아진다는 겁니다.

@Tag(name = "회원", description = "회원 관련 API")
@RestController
public class MemberController {
	@Operation(
		summary = "회원 로그인", 
		description = "회원 로그인을 할 수 있는 Endpoint",
		responses = {
			@ApiResponse(
				responseCode = "200", 
				description = "JWT 액세스 토큰과 리프레시 토큰"
			)
		}
	)
	@PostMapping("/login")
    public ResponseEntity<MemberLoginResponse> login(
            @Valid @RequestBody MemberLoginRequest loginRequest
    ) {
        return ResponseEntity.ok(memberService.login(loginRequest));
    }
}

 

  이런 Swagger를 만든 회사가 OpenApi Initiative에 스웨거 스펙을 기부를 하게되면서 OpenApi 스펙(OAS)이라는 명칭이 만들어지게 됩니다.

 

OpenApi3

 

  OpenApI 3.0의 yaml 모양은 다음 펫스토어 예제를 통해 확인해 볼수 있습니다. 다음 예제는 API 사양에 대한 여러 정보를 구조화하여 적어둔 스펙 파일이 되겠습니다.

Swagger Editor

RestDocs

  Swagger의 대안으로 나온 것이 RestDocs입니다. 스프링에서도 공식 지원을 하는 라이브러리를 만들었을 정도로 스프링에서 밀고 있는 API 자동화 툴입니다. RestDocs의 큰 장점으로는 테스트와 문서화를 접목시켰다는 점입니다. 컨트롤러 관련 테스트를 통과해야 문서 작성을 위한 스니펫이 만들어집니다. 아래는 멤버 로그인 테스트를 RestDocs 라이브러리로 작성한 코드입니다.

  ResultActions result = this.mockMvc.perform(post(URL_DOMAIN_PREFIX + "/login")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(request))
        );

// 아래 Expect를 통과해야 문서 스니펫이 만들어집니다.
result.andExpect(status().isOk())
        .andDo(document("member-login",
                resource(ResourceSnippetParameters.builder()
                        .tag(RESOURCE_TAG)
                        .description("멤버 로그인 API")
                        .requestSchema(Schema.schema(MemberLoginRequest.class.getSimpleName()))
                        .responseSchema(Schema.schema(MemberLoginResponse.class.getSimpleName()))
                        .requestFields(
                                fieldWithPath("email").type(JsonFieldType.STRING).description("멤버 이메일"),
                                fieldWithPath("password").type(JsonFieldType.STRING).description("멤버 비밀번호")
                        )
                        .responseFields(
                                fieldWithPath("access_token").type(JsonFieldType.STRING).description("JWT 액세스 토큰"),
                                fieldWithPath("refresh_token").type(JsonFieldType.STRING).description("JWT 리프레시 토큰"),
                                fieldWithPath("expires_in").type(JsonFieldType.NUMBER).description("JWT 액세스 토큰 만료 시간(초 단위)"),
                                fieldWithPath("name").type(JsonFieldType.STRING).description("회원 이름"),
                                fieldWithPath("email").type(JsonFieldType.STRING).description("회원 이메일")
                        )
                        .build()
                )
        ));

 

Swagger UI + OpenApi3 + RestDocs

  RestDocs의 테스트를 통한 문서자동화와 OpenApi3의 API 문서 구조화와 Swagger의 UI의 편리함을 모두 합한 라이브러리를 이용해보려 합니다. 바로 아래 RestDocs을 OpenApi 스펙으로 확장을 한 `epages-de/restdocs-api-spec` 라이브러리를 사용할 것입니다.

 

https://github.com/ePages-de/restdocs-api-spec

GitHub - ePages-de/restdocs-api-spec: Adds API specification support to Spring REST Docs

 

  Swagger-UI는 아래 링크에서 따로 다운을 받을 수 있고, zip 파일을 받은 후 압축된 폴더 내의 `dist` 디렉토리 안의 파일들만 이용할 것입니다.

https://github.com/swagger-api/swagger-ui/releases

Releases · swagger-api/swagger-ui

 

  다음 포스팅에서 위 두 라이브러리를 이용하여 API 문서화를 진행해보도록 하겠습니다.