REST API DOCS 응용

https://dev-elop.tistory.com/29

REST API DOCS

기본 테스트가 끝났다면 테스트한 것을 토대로 이쁜 HTML 화면을 위해 응용을 해보자.

 

참고 URL : http://woowabros.github.io/experience/2018/12/28/spring-rest-docs.html

Spring Rest Docs 적용 - 우아한형제들 기술 블로그

우아한 형제들 블로그 참고해서 ApiDocumentUtils.java 파일 만들고 했으나 문서 생성 과정이 다른점이 많아 추가한다. 

request field 와 response field 설명서를 만들어야 하는데 기존 블로그들과는 좀 달라서 개인적으로 작성했다. 

//request
List<FieldDescriptor> requestFieldDescriptorList = new ArrayList<FieldDescriptor>();
FieldDescriptor requestFieldDescriptor = PayloadDocumentation.fieldWithPath("username").type(JsonFieldType.STRING).description("사용자이름");
requestFieldDescriptorList.add(requestFieldDescriptor);

RequestFieldsSnippet requestFieldsSnippet = PayloadDocumentation.requestFields(requestFieldDescriptorList);

//response
List<FieldDescriptor> responsefieldDescriptorList = new ArrayList<FieldDescriptor>();
FieldDescriptor username = PayloadDocumentation.fieldWithPath("username").type(JsonFieldType.STRING).description("사용자이름");
FieldDescriptor statusCode = PayloadDocumentation.fieldWithPath("statusCode").type(JsonFieldType.NUMBER).description("상태코드");
responsefieldDescriptorList.add(username);
responsefieldDescriptorList.add(statusCode);
ResponseFieldsSnippet responseFieldsSnippet = PayloadDocumentation.responseFields(responsefieldDescriptorList);

field 작성후 다시 문서 작성

/*  
 *  테스트 post 주소 지정
 *  콘텐츠 타입 지정
 *  어셉트 타입 지정
 */ 
ResultActions resultActions = mockMvc.perform(post("/url1/url2")
				.content(objectMapper.writeValueAsString(parameter))
				.contentType(MediaType.APPLICATION_JSON)
		        .accept(MediaType.APPLICATION_JSON));
                
/*  
 *  andExpect - http 결과가 200 일때만
 *  document - 결과 문서가 주소처럼 이쁘게 생성됨	
 *  ApiDocumentUtils - 파일로 생성한 java 파일                                                                         
 *  requestFieldsSnippet, responseFieldsSnippet - 이부분이 기존과 다르더라..
 */ 
resultActions.andExpect(status().isOk())
			.andDo(document("/url1/url2", 
					ApiDocumentUtils.getDocumentRqeust(), 
					ApiDocumentUtils.getDocumentResponse(),
					requestFieldsSnippet,
					responseFieldsSnippet
					)
				);                

 

코드 작성후 테스트 다시 해보고

maven install 하면 문서가 작성된다. 작성된 문서는 소스파일 위치 말고 target!! 그러니깐 배포 위치에 생성된다.

 

생성된 파일은 *.adoc 같은 파일들인데. 이건 html 파일로 만들기전 내용들의 조각이라고 생각하면 된다. 

이 파일들을 합쳐서 html로 만들기 위해선 다시

adoc 파일들을 합쳐라! 라고 하는 일종의 프로퍼티 파일이 하나 필요하다. 

아무것도 안하면 기본설정 폴더는 src/main/asciidoc/ 일것이다. 

 

include::{snippets}/ur1/url2/http-request.adoc[]

 

가장 기본적인 문법은 위와 같지만 이 문서 만들기 문법은 asciidoc 를 검색해서 찾길 바란다.

최종적으로 만들어지는 기본 HTML 경로는

 

{url}/docs/api-docs.html