Restdocs와 Swagger UI 연동해서 EC2에 배포하기

Why?

---

• 팀 프로젝트를 하면서 애플리케이션 코드에 문서화를 위한 코드를 추가하는 것이 마음에 들지 않아 RestDocs를 선택했다.
• 하지만 RestDocs는 별로이쁘지 않았고, Swagger처럼 바로 호출할 수 없다는 단점이 있었다.

 

Need?

---

plugins {
    // api-spec 플러그인 추가
    id 'com.epages.restdocs-api-spec' version '0.16.0'
}

dependencies {
    // api-spec 의존성 추가
    testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.16.0'
}

// openapi3 task 추가, 문서화 할 때 아래 정보를 참조해서 만들어진다.
openapi3 {
    server = 'http://3.39.184.232:8080'
    title = 'Tenwonmoa API'
    description = 'Tenwonmoa API description'
    version = '1.0.0'
    format = 'yaml'
}

// build 후 생성된 openAPI문서를 src/main/resource 하위로 복사하기 위한 task를 추가한다.
task copyOpenApi(type: Copy) {
    from file("build/api-spec")
    into file("src/main/resources/static/docs")
}

// build 후 생성된 openAPI문서를 복사하는 task를 수행한다.
build {
    dependsOn copyDocument
    finalizedBy 'copyOpenApi'
}

 

How?

---

• RestDocs에서 OpenAPI Spec 추출.
  • restdocs-api-spec라이브러리를 사용하여 RestDocs를 작성하면 된다.
  • 2개의 import만 변경해서 사용하면 된다.

// import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*;
import static com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper.*;
// import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*;

• Swagger UI를 실행시킨다.
  • Swagger UI에서 추출한 OpenAPI를 확인할 수 있다.
  • Docker-Container를 통해 Swagger UI를 실행한다.

 

배포?

---

• ec2내에서 docker-compose를 통해 Swagger-UI를 실행시켰다.
• 8082 포트 요청을 받아 compose내의 8080 포트로 떠있는 Swagger-UI로 포워딩하게 한다.
• 배포 과정에 docker-compose를 실행시키도록 추가한다.

version: "3.7"
services:
  tenwonmoa-swagger:
    image: swaggerapi/swagger-ui
    container_name: tenwonmoa-swagger
    ports:
      - 8082:8080
    environment:
      API_URL: {URL}:8080/docs/openapi3.yaml

 

결과 확인

---

 

후기

---

• RestDocs와 SwaggerUI를 연동시킴으로써 애플리케이션 코드에 불필요한 코드를 작성하지 않아도 되었고, UI적으로도 보기 좋은 문서화가 가능했다.
• docker-compose에 익숙하지 않아서 배포하는 과정에서 port설정을 헷갈려서 애를 먹기는 했지만.. 그래도 팀원의 도움을 받아 해결할 수 있었다.
• 결과적으로 front와의 협업하는 데 있어 swagger를 제공하여 생산성을 높이고, 백엔드 입장에서도 의도한 대로 문서화를 할 수 있었다.

 

참조

---

• 팀원이 정리한 글
• https://taetaetae.github.io/posts/openapi-and-swagger-ui-in-spring-boot/
• https://taetaetae.github.io/posts/a-combination-of-swagger-and-spring-restdocs/
• https://blog.naver.com/qjawnswkd/222340413113