Spring REST Docs Easy: 효율적인 API 문서화 도구 (spring-restdocs-easy)

Spring REST Docs Easy: 효율적인 API 문서화 도구

소개

Spring REST Docs Easy는 Spring REST Docs를 확장하여 API 문서화를 더 쉽게 만드는 라이브러리입니다. 테스트 기반 문서화와 국제화 지원을 결합하여 정확하고 관리하기 쉬운 API 문서를 생성할 수 있습니다.

https://github.com/syakuis/spring-restdocs-easy

설치 방법

Gradle

dependencies {
    testImplementation 'io.github.syakuis:spring-restdocs-easy:1.0.0'
}

실제 사용 예제

1. 기본 설정

@WebMvcTest(MemberRestController.class)
@AutoConfigureMvcRestDocs
class MemberRestControllerTest {
    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private RestDocs restDocs;

    private final String RESTDOCS_PATH = "members/{method-name}";
}

2. GET 요청 문서화 (목록 조회)

@Test
void list() throws Exception {
    mockMvc.perform(get("/members")
            .param("name", "stela")
            .param("age", "10")
            .param("job", "ENGINEER")
            .param("email", "email@email.com")
            .accept(MediaType.APPLICATION_JSON))
        .andExpect(status().isOk())
        .andDo(document(RESTDOCS_PATH,
            // 요청/응답 헤더 문서화
            restDocs.headers()
                .add(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON)
                .requestHeaders(),
            restDocs.headers()
                .add(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON)
                .responseHeaders(),

            // 쿼리 파라미터 문서화
            restDocs.params()
                .add("name", "name parameter")
                .add("age", "{io.github.syakuis.spring.restdocs.easy.examples.adapter.web.controller.model.MemberRequest.age}")
                .add("job", restDocs.generate(Job.class).join())
                .add("email", "{email}")
                .queryParameters(),

            // 응답 필드 문서화 (배열 응답)
            restDocs.generate("[].", MemberResponse.class)
                .addAll("[].locationAddress.", LocationAddress.class)
                .responseFields()
        ));
}

3. POST 요청 문서화 (등록)

@Test
void register() throws Exception {
    MemberRequest request = new MemberRequest("John Doe", 30, Job.ACCOUNTANT, 
        "john@example.com", true, List.of("tag1", "tag2"), 
        new LocationAddress("123 Main St", "City", "Country"));

    mockMvc.perform(post("/members")
            .contentType(MediaType.APPLICATION_JSON)
            .header(HttpHeaders.AUTHORIZATION, "")
            .content(objectMapper.writeValueAsString(request)))
        .andExpect(status().isOk())
        .andDo(document(RESTDOCS_PATH,
            // 요청 헤더 문서화
            restDocs.headers()
                .add(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON)
                .add(HttpHeaders.AUTHORIZATION, "{http.headers.authorization.BASIC_AUTHORIZATION}")
                .requestHeaders(),

            // 요청 본문 필드 문서화
            restDocs.generate(MemberRequest.class)
                .requestFields()
                .andWithPrefix("locationAddress.", restDocs.generate(LocationAddress.class).toField()),

            // 응답 본문 필드 문서화
            restDocs.generate(MemberResponse.class)
                .responseFields()
                .andWithPrefix("locationAddress.", restDocs.generate(LocationAddress.class).toField())
        ));
}

4. 단일 조회 문서화 (경로 변수 포함)

@Test
void view() throws Exception {
    mockMvc.perform(get("/members/{id}", 953))
        .andExpect(status().isOk())
        .andDo(document(RESTDOCS_PATH,
            // 경로 변수 문서화
            restDocs.params().add("id", "id").pathParameters(),

            // 응답 필드 문서화
            restDocs.generate(MemberResponse.class)
                .responseFields()
                .andWithPrefix("locationAddress.", 
                    restDocs.generate(LocationAddress.class).toField())
        ));
}

주요 기능 설명

1. 다양한 문서화 지원

• 요청/응답 헤더 (headers())
• 쿼리 파라미터 (params())
• 경로 변수 (pathParameters())
• 요청/응답 필드 (requestFields(), responseFields())
• 중첩 객체 (andWithPrefix())
• 배열 응답 ([] 표기법)

2. 메시지 소스 활용

• 직접 문자열 설명 사용 가능
• 메시지 키를 통한 국제화 지원 ({key} 형식)
• 클래스의 필드 설명 자동 참조

3. 중첩 구조 처리

• addAll(): 중첩 객체의 필드 추가
• andWithPrefix(): 중첩 필드 경로 지정
• 배열 표기법([].)을 통한 컬렉션 처리

장점

1. 코드 중복 최소화
2. 직관적인 API
3. 유연한 문서화 옵션
4. Spring REST Docs의 장점 유지
5. 국제화 지원

결론

Spring REST Docs Easy는 Spring REST Docs의 기능을 확장하면서도 사용하기 쉬운 API를 제공합니다. 특히 중첩된 객체 구조나 배열 응답의 문서화를 간단하게 처리할 수 있어, 복잡한 API의 문서화 작업을 크게 단순화합니다.