spring rest docs 기반의 문서화 및 사용법

[unikal1]

API 문서화를 위해 spring rest docs를 사용하고자합니다.. 개인적으로 swagger 는 음, 실제 코드 부분에 있어서 변경을 요한다는 점이 단점으로 작용한다고 봅니다 저는.

어쨋거나, 사용 방법을 아실 수도 있겠다만, 혹시나 해서 기본적인 틀 자체는 공유를 하고자 합니다.

현재 작업 중인 브랜치는 test/security-test 입니다.

대부분은 build.gradle에 그 절차가 명시되어 있습니다. 이는 결국 실제 빌드되는 과정에서 테스트 후 문서를 생성하고, 해당 문서에 따른 html 을 생성/copy 한다는 단계입니다.

실제 문서 자체는 localhost:8080/docs/index.html 로 들어가면 있습니다.

기본적인 spring rest docs와 다르게, 저같은 경우는 api 별로 여러 페이지를 생성하는 것을 선호합니다. 기존에는 하나의 index.html에 모든 api 가 전부 들어가 있어서 스크롤이 매우 길어지고 보기도 불편하지만, 해당 프로젝트는 도메인 별로 adoc 및 html을 생성하여 링크를 통해 다른 페이지로 옮기는 방식을 사용하려 합니다. 이를 위해, 추후 새로운 도메인에 대해 페이지를 추가할 경우 다음 과정이 필요합니다.

1. src/asciidoctor/api 에 [domain].adoc 생성 / 템플릿은 다른 adoc 을 보고 참조
2. index.doc 에 해당 문서에 대한 url 추가

그 외 새로운 기능 코드, 오류 코드는 data 디렉토리 안에 넣으시면 됩니다.

추후, 실제 통합 테스트에서 어떤 식으로 사용할건지와, 이를 위한 유틸리티를 구성하고 추가할 예정입니다. 기본적으로 생각하는 것은 다음과 같습니다.

• 문서에 포함할 항목을 다음과 같이 제한하고, 형식을 강제합니다.

    @Bean
    public RestDocumentationResultHandler restDocumentationResultHandler() {
        return MockMvcRestDocumentation.document(
                "{class-name}/{method-name}",  // 문서 이름 설정
                preprocessRequest(  // 공통 헤더 설정
                        modifyHeaders()
                                .remove("Content-Length")
                                .remove("Host"),
                        prettyPrint()),  // pretty json 적용
                preprocessResponse(  // 공통 헤더 설정
                        modifyHeaders()
                                .remove("Content-Length")
                                .remove("X-Content-Type-Options")
                                .remove("X-XSS-Protection")
                                .remove("Cache-Control")
                                .remove("Pragma")
                                .remove("Expires")
                                .remove("X-Frame-Options"),
                        prettyPrint())
        );
    }

[unikal1]

실제 화면 예시는 다음과 같습니다.

[s0o0bn]

좋습니다!
저도 대충 뭔지만 알고 실제로 해본 적은 아직 없어서, 이번 기회에 활용법을 공부해봐야겠네요 ㅎㅎ