Spring REST Docs 의 Getting Started

어제는 SWAGGER 연동을 해보고, 오늘은 Spring REST Docs에 Getting Started 를 정리 해 봤다.

최종은 아래와 같은 html를 제공하는 것이다.

http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/samples/restful-notes/api-guide.html

요렇게 나오는 것이 목표입니다. 

Sample Applications

https://github.com/spring-projects/spring-restdocs/tree/master/samples

보시면 알겠지만, 사용가능한 Sample Application 두개가 있습니다.

하나는 Spring HATEOAS를 사용하고, 또 다른 하나는 Spring Data REST 를 사용합니다.

두 예제 모두 상세한 API 가이드와 getting started를 제공하는 Spring REST Docs를 사용하니까, 뭘 보든지 상관없겠죠?

우리는 Spring-data-rest를 기준으로 작업을 할 터이니, rest-notes-spring-data-rest를 파 보도록 합시다.

각 예제는 해당 서비스를  위한 API 가이드를 생산하는 api-guide.adoc  이라는 파일을 포함하고 있습니다.

그리고 getting started 가이드를 생산하는 getting-started-guide.adoc 이라고 명명된 파일도 있습니다.

*api-guide.adoc

이렇게 우선 만들어서 java/main/asciidoc/ 폴더에 생성 해서 넣어 놨습니다.

특징은 include 부분인데.. 이게 곧 설명하겠지만, 테스트를 거치면서, 발생 한 snippets이 들어가는 것이랍니다.

추가적으로 AsciiDoc 태그 공부를 좀 해야 되겠죠 ( http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ )

*getting-started-guide.adoc

발생한 조각들(snippets)를 생성하는 코드는 src/test/java 에서 찾을 수 있습니다.

다시 말해, 단위 테스트를 진행하는 ApiDocumentation.java가 API 가이드를 위한 조각들(snippets)를 생성합니다.

또한 GettingStartedDocumentation.java은 getting started 가이드를 위한 조각들(snippets)를 생성하겠지요?

ApiDocumentation.java

Build configuration

Spring REST Docs를 사용하는데 있어서, 첫번째 단계로 우리의 project의 빌드를 구성하는 것입니다.

     - Gradle Build configuration : 생략합니다.

        Spring HATEOAS 예제는 build.gradle 파일을 포함하고 있네요. 우리는 무조건 maven으로 갑시다.

 

     - Maven build configuration 

        Spring Data REST 예제는 pom.xml 파일을 포함하니까, 직접 가서 확인해보셔도 됩니다. 

        구성에 핵심 부분은 아래 설명이 잘 되어 있네요. 

      

         1. test scope 상에 spring-restdocs-mockmvc  dependency 추가합니다. 

              scope를 test에 두지 않으면 어떻게 될지도 궁금하네요...

          

         2. 발생한 조각들(snippets)에 대한 output 위치를 표시하는 property 구성 합니다. 

              프로젝트가 빌드되는 곳에 generated-snippets 상에 생성이 되라고 했네요.

          

        3. SureFire 플러그 인을 추가 하고 Documentation.java로 끝나는 이름의 파일들을 플러그인에 포함하는 설정합니다. 

   

          

       

         4. Asciidoctor 플러그 인을 추가합니다.

         5. 우리 documentation 상에 생성된 조각들(snippets)를 포함 할 때 사용할 수 있는 snippets 이라는 이름의 속성을 정의 합니다. 

               

         6. 만약 우리 프로젝트의 jar 파일안에 documentation를 포함시키길 원한다면, 우리는 prepare-package 구문을 사용해야 합니다.

          

      - Packaging the document

         예를 들어 Spring Boot에 의해서 정적 컨텐츠로 제공된 것을 갖기 위해, 프로젝트의 jar 파일상에서 발생한 documentation 를 패키징 하길 원할 것이다.

         우선 생성한 documentation를 그 프로젝트의 jar안에 포함되어 질 곳인 location안에 복사하기 위해 Maven의 리소스 플러그인을 설정합니다. 

         1. Asciidoctor 플러그인을 위해 존재하는 선언.

          

         2. 리소스 플러그인은 같은 phase(prepare-package)에 묶여지는 것으로써 Asciidoctor 플러그인 이후에 선언되어져야 하고,

            리소스 플러그인은 Asciidoctor 플러그인 후에 동작되어야만 합니다.

          위에서 src/main/asciidoc에 있는 api-guide.adoc 과 getting-started-guide.adoc 이

          api-guide.html , getting-started-guide.html 로 변환이 되고,

          static/docs 으로 api-guide.html , getting-started-guide.html이 카피되는 것 같습니다. 

Generating documentation snippets

Spring REST Docs은 여러분이 문서화할 서비스에 요청들을 만들기 위해 Spring의 MVC Test framework를 사용합니다.

그때, 요청과 응답 결과을 내는 것을 위해 documentation snippets를 생산해 보도록 하겠습니다.

      - Setting up Spring MVC test

     documentation snippets를 생성하는 첫번째 단계는 JUnit의 @Rule 이라는 어노테이션이 붙은 public RestDocumentation 필드를 선언하는 것입니다. 

     그리고 MockMvc 인스턴스를 생성하는 @Before 메소드를 제공합니다. 

     RestDocumentation Rule은 생성된 snippets이 쓰여져야 하는 곳에 output 디렉토리와 함께 설정됩니다.

     이 output 디렉토리는 여러분이 pom.xml 파일안에 설정해 놓은 snippets 디렉토리와 매칭되어야 합니다.

     MockMvc 인스턴스는 RestDocumentationMockMvcConfigurer를 사용하여 설정됩니다.

     이 클래스의 인스턴스는 org.springframework.restdocs.mockmvc.MockMvcRestDocumentation 상에 정적 메소드,
    documentationConfiguration()으로 부터 얻을수 있습니다.

     

     RestDocumentationMockMvcConfigurer는 똑똑한 기본값을 적용하고, 또한 설정을 커스터마이징하는 것을 위해 API를 제공합니다. 

     더 많은 정보는 configuration section를 참고하세요.

     http://docs.spring.io/spring-restdocs/docs/current/reference/html5/#configuration

     - Invoking the RESTful service

     MockMvc 인스턴스가 생성되었고, RESTful 서비스를 발생시키는 것에 사용되어 질수 있고, 요청과 응답을 문서화 합니다.

     예를 들어 볼까요?

     

this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))   // 1           .andExpect(status().isOk())     // 2           .andDo(document("index"));   //3

     1. 서비스의 root를 발생하고 application/json 응답이 요구되어지는 것을 가르킨다.

     2. 이 서비스는 예상된 응답을 제공하는 것을 가정한다.

          서비스를 호출하는 것을 문서화 하고,  설정한 output 디렉토리아래 위치하게 될 index 라는 이름의 디렉토리 안에 snippets를 작성한다.

          그 snippets은 RestDocumentationResultHandler에 의해 작성 됩니다.

     3. 이 클래스의 인스턴스는 org.springframework.restdocs.mockmvc.MockMvcRestDocumentation 상에 정적 document 메소드로 부터 얻어 질수 있습니다. 

          

     기본으로, 세개의 snippets이 작성됩니다.

     - <output-directory>/index/curl-request.adoc

     - <output-directory>/index/http-request.adoc

     - <output-directory>/index/http-response.adoc

   이들에 대한 더 많은 정보, Spring REST Docs에 의해 생성되어질 수 있는 다른 snippets에 대해 알고 싶다면,  Documenting your API를 참고하세요. 

     http://docs.spring.io/spring-restdocs/docs/current/reference/html5/#documenting-your-api

    - Using the snippets

    생성된 snippet은 include macro 를 사용하여(http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files) 여러분의 documentation안에 포함되어 질수 있습니다.

     build configuration 안에 명시해 놓은 그 snippets 속성은 snippets 아웃풋 디렉토리를 참조하는데 사용되어 질수 있습니다.    

    

     예를 들면,

     

include::{snippets}/index/curl-request.adoc[]

참고 하실래요?

Making your API easy to document with Spring REST Docs : http://slides.com/gmind7/spirngrestdocs 

RESTful Notes API Guide : http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/samples/restful-notes/api-guide.html

(여기서 참고해서 API Guide 만들어도 좋을 듯) 

이상입니다.