[Key Word 개발기] Spring RestDocs 와 Swagger 같이 사용하기

원래 협업 프로젝트때 Spring RestDocs를 통해서 api 문서를 만들려고 했다.

그런데 귀찮은 부분이 있었다. 

 

첫번째 adoc파일을 직접 디자인??해야된다는 점

두번째 문서가 추가되면 asciido 문서를 일일이 편집해야한다는 점

세번째 swagger처럼 직접 테스트 해볼 수 없다는 점이다.

 

거기다가 팀원분들이 대부분 swagger는 해보셨는데 RestDocs는 처음 사용하시는 것같았다...사실 나는 둘다 사용안해봄...

 

그런데 찾아보니 Spring RestDocs랑 Swagger를 같이 쓸 수 있는 방법이 있었다.

 

---

 Swagger UI + Spring Rest Docs

 

 

 

위에가 전체적인 흐름이다

1. 기존처럼 테스트코드를 통해 docs문서를 생성

2.docs문서를 openApi3스펙으로 변환

3.만들어진 openApi3을 Swagger UI로 생성

4.생성된 Swagger UI를 static 패키지에 복사 및 정적 리소스로 배포

 

매우 간단하다. 사실 restDocs를 사용해봤다면 코드 몇개 수정하고 디펜던시만 추가하면 끝난다.

 

Build.gradle

plugins {
	id 'java'
	id 'org.springframework.boot' version '2.7.17'
	id 'io.spring.dependency-management' version '1.1.4'
    //open-ai플러그인 추가
	id "com.epages.restdocs-api-spec" version "0.16.4"
    //swagger-ui추가
	id 'org.hidetake.swagger.generator' version '2.18.2'
}

dependencies{
	//RestDocs 추가
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
    //OpenAPI3 추가
	testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.16.4'
    //Swagger-UI추가
	implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.7.0'
}

//GenrateSwaggerUI태스크가 openapi3 task를 의존하도록 설정
tasks.withType(GenerateSwaggerUI){
	dependsOn'openapi3'

	delete file('scr/main/resources/static/docs')
	copy{
		from "build/resources/main/static/docs"
		into "src/main/resources/static/docs"
	}
}

bootJar {
	dependsOn('openapi3')
}
//부가 정보들 
openapi3 {
	server = "http://localhost:8086"
	title = "THT API 문서"
	description = "Spring REST Docs with SwaggerUI."
	version = "0.0.1"
	outputFileNamePrefix = 'open-api-3.0.1'
	format = 'json'
	outputDirectory= 'build/resources/main/static/docs'
}

 

기본 buildgradle에 이부분을 추가했다. 일단 springframework.boot는 2.7.X이고 java버전은 1.8이다.

왠만큼 불필요한 설정이라고 생각되는 부분 뺀건데 혹시 더 뺄수 있는 부분이 있다면 댓글로 누군가가 알려줬으면...ㅎㅎ

 

boot를 3.x대 사용한다면 제가 만든 restdocs-test 레포를 보시면 있습니다.(의존성 정리를 대충했는데 그래도 어느정도 참고 가능하실꺼에요!)

 

테스트 코드

 

  @Test
  void existMemeber() throws Exception {
    //given
    MemberDto dto=MemberDto.builder()
        .age(10)
        .name("hello")
        .build();
    MemberResponse response=MemberResponse.builder()
        .name("hello")
        .build();

    given(memberService.checkMember(any()))
        .willReturn(response);

    mockMvc.perform(get("/member/{id}",1)
            .contentType(MediaType.APPLICATION_JSON)
            .content(objectMapper.writeValueAsString(dto)))
        .andDo(print())
        .andDo(document("members/checkMember",
            preprocessRequest(prettyPrint()),
            preprocessResponse(prettyPrint()),
            pathParameters(
                parameterWithName("id").description("id에 대한 설명")
            ),
            requestFields(
                fieldWithPath("name").type(JsonFieldType.STRING).description("MemberDto name 설명"),
                fieldWithPath("age").type(JsonFieldType.NUMBER).description("MemberDto age 설명")
            ),
            responseFields(
                fieldWithPath("name").type(JsonFieldType.STRING).description("MemberResponse name 설명")
            )))
        .andExpect(MockMvcResultMatchers.status().isOk());
  }

 

아주아주 간단한 테스트코드다.

docs만 사용했을때라 다른점은

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;

 

에서

import static com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper.document;

 

로 변경하면 된다. 

 

이후 테스트 코드가 성공하면 

Gradle -> documentations -> generateSwaggerUI 클릭

 

하면 src/main/resources/static/docs에 open-api-3.0.1 json이 생긴다

 

springdoc.default-consumes-media-type=application/json;charset=UTF-8
springdoc.default-produces-media-type=application/json;charset=UTF-8
springdoc.swagger-ui.url=/docs/open-api-3.0.1.json
springdoc.swagger-ui.path=/docs/swagger

 

application.properties에 이렇게 설정하면 localhost:port/docs/swagger쪽으로 들어가면 swagger로 api문서를 볼 수 있다.

 

 

---

아직 스프링 시큐리티를 적용안해서 이게 토큰에 대해 어떻게 되야하는지 잘모르겠다. 참고한 블로그 보니까 이부분에서 고민하시고 해결하시것같은데... 문제를 만나야 뭐 해결해보지 않을까..?

아 부트캠프 미션 프로젝트때 한걸로 적용해볼까..?

 

일단 오늘 정리 끝!

 

https://velog.io/@hwsa1004/Spring-restdocs-swagger-%EA%B0%99%EC%9D%B4-%EC%82%AC%EC%9A%A9%ED%95%98%EA%B8%B0