REST Docs

REST Docs와 Asciidoctor를 사용하여 API 문서를 자동으로 생성하고 배포

1. 테스트 실행 (`./gradlew test`)

목적: Spring REST Docs를 사용하여 API 요청과 응답을 기반으로 스니펫을 생성합니다.

Gradle test 태스크를 실행하면, 테스트 코드에서 API에 대한 요청 및 응답을 실행합니다.

UserController

@RestController
@RequestMapping("/api/user")
public class UserController {

    @GetMapping("/users")
    public ResponseEntity<Map<String, Object>> getUserInfo() {
        Map<String, Object> response = new HashMap<>();
        Map<String, Object> userInfo = new HashMap<>();

        userInfo.put("nickname", "고도연");
        userInfo.put("birth", "2000.01.20");
        userInfo.put("gender", "FEMALE");
        userInfo.put("residence", "Mokpo");
        userInfo.put("selfIntroduction", "안녕하세요, 저는 개발자입니다.");

        response.put("success", true);
        response.put("response", userInfo);
        response.put("error", null);

        return ResponseEntity.ok(response);
    }
}

UserControllerTest

@WebMvcTest(UserController.class)
@AutoConfigureRestDocs // REST Docs 사용
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    @DisplayName("사용자 기본 정보 API")
    void getUserInfo() throws Exception {
        // 실제 컨트롤러에서 반환하는 응답을 검증
        mockMvc.perform(get("/api/user/users")
                        .contentType(MediaType.APPLICATION_JSON))
                .andDo(print())  // 요청 및 응답을 출력
                .andExpect(status().isOk())  // 기대하는 상태 코드 200 (OK) 검증
                .andDo(document("user-info",  // API 문서화
                                preprocessResponse(prettyPrint()),  // 응답을 보기 좋게 출력
                                responseFields(
                                        fieldWithPath("success").type(JsonFieldType.BOOLEAN)
                                                .description("성공 여부"),
                                        fieldWithPath("response.nickname").type(JsonFieldType.STRING)
                                                .description("사용자 이름"),
                                        fieldWithPath("response.birth").type(JsonFieldType.STRING)
                                                .description("사용자의 생년월일"),
                                        fieldWithPath("response.gender").type(JsonFieldType.STRING)
                                                .description("성별"),
                                        fieldWithPath("response.residence").type(JsonFieldType.STRING)
                                                .description("거주지"),
                                        fieldWithPath("response.selfIntroduction").type(JsonFieldType.STRING)
                                                .description("자기소개"),
                                        fieldWithPath("error").type(JsonFieldType.NULL)
                                                .description("에러 정보 (없을 경우 null)")
                                )
                        )
                );
    }
}

테스트가 실행되면서, 스니펫 파일들이 자동으로 생성됩니다. 이 스니펫 파일들은 REST Docs에서 HTTP 요청 정보, HTTP 응답 정보, 필드 설명 등을 기록한 파일들입니다.
이 스니펫 파일들은 build/generated-snippets/ 디렉토리에 저장됩니다.

//build.gradle
ext {
    set('snippetsDir', file("build/generated-snippets"))
}

예를 들어, user-info라는 API에 대한 스니펫 파일이 build/generated-snippets/user-info/ 경로에 저장되며, 여기에 http-request.adoc, http-response.adoc, response-fields.adoc 파일들이 생성됩니다.

이후 .adoc 파일을 참조하는 index.adoc 파일을 src/docs/asciidoc/ 하위에 만든다.

//index.adoc

= API Documentation

== 사용자 기본 정보 API

include::{snippets}/user-info/http-request.adoc[]
include::{snippets}/user-info/http-response.adoc[]
include::{snippets}/user-info/response-fields.adoc[]

REST Docs

1. 테스트 실행 (./gradlew test)

1. 테스트 실행 (`./gradlew test`)