Spring Rest Docs 적용 2 - Swagger 연동

 지난번 마지막 포스팅을 한 후 한참이 지나서야 다시 포스팅을 하게 됐습니다.

 

그래도 시작한 거에 대해 마무리를 지어야 하니 개인적으로 정리했던 내용들을 블로그에 다시 정리해 보려 합니다!

 

앞 포스팅은 다음 링크에 있으니 아직 확인하지 못하신 분들은 먼저 읽으신 후에 현재 포스팅을 읽어주시면 감사하겠습니다!

 

 

Spring Restdocs 적용

 

앞선 포스팅에서 Restdocs 로 문서화하는 과정을 살펴봤는데요

 

이제는 해당 Restdocs 결과물을 더 가독성 좋게 Swagger로 변환하는 과정을 정리해 보고자 합니다

 

1. gradle에서 필요한 dependency 를 추가해야 되는데 다음과 같이 필요합니다

 

buildscript {
	ext {
		restdocsApiSpecVersion = "0.19.4" //버전을 인관되게 사용하기 위한 선언
	}
}


plugins {
	//rest doc 을 oas file generate
	id "com.epages.restdocs-api-spec" version "${restdocsApiSpecVersion}"
	// oas file 을 swagger ui 로 생성
	id "org.hidetake.swagger.generator" version "2.19.2"
}

 

1) restdoc 을 oas으로 만들기 위한 dependency

2) 생성된 oas 파일을 토대로 swagger를 생성하기 위한 dependency

 

이렇게 준비를 해주시면 됩니다!

 

 

선택 사항이지만, 저는 build.gradle 에 restdoc 관련된 코드를 작성하기 복잡하여 별도로 restdoc.gradle 파일을 생성하여 작업했습니다.

 

그래서 build.gradle 에 있는 dependency를 활용하기 위해 restdocs.gradle 상단에 추가해 줬습니다.

 

apply plugin: 'com.epages.restdocs-api-spec'
apply plugin: 'org.hidetake.swagger.generator'

 

2. restdocs.gradle 에서 swaager 관련된 설정을 하여 build time에 oas 관련 파일을 swaager에 설정을 진행해 줍니다

  1) swagger 생성에 필요한 yaml 파일 위치 및 스웨거가 생성된 후 저장되는 디렉터리를 미리 빼놓습니다! (추후 스웨거 생성 과정에서 사용할 값들) 

def generatedOpenapi3YamlFile = layout.buildDirectory.dir("api-spec/openapi3.yaml").get()
def swaggerPath = layout.buildDirectory.dir("swagger-ui-sample")

2) openapi spec에 대해 구성 옵션을 추가합니다. 생성되는 yaml 포맷 및 기타 정보들

openapi3 {
    def host = System.getenv('HOST')
    if (host == null) {
        host = "http://localhost:8080"
    }
    logger.lifecycle("current host : ${host}")
    setServer("${host}") // API 요청을 보낼 서버 주소 설정
    title = "restdocs-swagger API Documentation" // API 문서 제목
    description = "Spring REST Docs with SwaggerUI." // API 문서 설명
    version = "0.0.1" // API 문서 버전
    format = "yaml" // API 문서 출력 포맷 (default = JSON)
}

 

 

  3) 스웨거 ui 생성 및 restdoc 설정에 필요한 디펜던시 추가

• 추후 테스트 코드에서 사용될 디펜던시입니다.

dependencies {
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc' // (4)

    //restdoc 설정 추가
    testImplementation "com.epages:restdocs-api-spec-mockmvc:${restdocsApiSpecVersion}"

    //swagger ui 관련된 디펜던시 추가 generateSwaggerUISample 에서 사용되는 ui 디펜던시
    swaggerUI 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
}

 

  4) 스웨어 생성 후 카피 경로 설정 - 추후에 static 폴더로 옮겨 서버 기동 후에 접근할 수 있도록 생성된 스웨거 문서를 복사합니다

tasks.register('copySwaggerUI', Copy) {
    dependsOn 'generateSwaggerUISample'

    from(swaggerPath)
    into("./src/main/resources/static/docs")

    logger.lifecycle("Copying from ${swaggerPath} to src/main/resources/static/docs")
}

 5) 스웨거 생성 시 openapi3 가 먼저 실행되어 yaml 파일이 수행되도록 합니다.

tasks.withType(GenerateSwaggerUI).configureEach {
    dependsOn 'openapi3'
}

 6) bootJar를 통해 swagger 가 테스트코드가 성공하면 생성되도록 설정합니다.

bootJar {
    archiveFileName = "${rootProject.name}.jar"
    dependsOn test
    logger.lifecycle("create docs")
    dependsOn copySwaggerUI
}

 

 

3. 테스트 코드에서 조회 및 생성에 대한 controller test를 진행하고 문서에 대해 정의합니다 

• 코드는 github 참고 & 추후 테스트에 대해서는 따로 작성하도록 하겠습니다.

 

4. bootJar를 수행해 보면 다음과 같이 build 디렉터리에 문서가 생성된 것들 확인할 수 있습니다.

 

bootJar 이후 build 결과물

 

5. 해당 결과물은 static/docs로 복사를 해놨고, static 파일에 접근하기 위해 WebConfig를 추가로 설정해 줬습니다.

@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
    }

}

 

6. localhost/docs/index.html로 접근하면 다음과 같이 완성된 Swagger 가 나온 것을 확인할 수 있습니다.

 

 

지난번 restdoc 생성에 이어 swagger로 띄우는 것까지 진행을 해봤습니다. 테스트 코드 부분은 여기서 설명하지 않고 다음 포스팅에서 설명하도록 하겠습니다.

 

프로젝트 진행 중 도입했던 스웨거 도입까지 정리하였습니다.

 

테스트를 통한 문서 생성이라 테스트가 실패하면 문서가 생성되지 않습니다. 따라서 테스트 강제 및 그에 따른 컨트롤러 검증이 따라오므로 코드의 안정성이 확실히 증가되는 경험을 할 수 있었습니다.

 

완성된 코드입니다 테스트 코드도 같이 있으니 참고하셔서 프로젝트에 도움이 되셨으면 좋겠습니다!

 

GitHub - jjjwodls/restdoc-and-swagger

 

 

이상입니다!