[EatPick] 협업을 위한 Swagger 배포하기(1)

 본격적인 개발에 들어가기에 앞서 원활한 협업을 위해서는 현재, 그리고 앞으로 구현될 API를 명세할 필요가 있다. 그럼 Notion에 일일히 정리해야 하는가?🤔 이 방법은 너무 비효율적이라는 생각이 들었다. 따라서 Swagger 배포 및 자동화 방법을 모색해봤다.

 

1. Swagger 배포를 위한 여러가지 방법

(1) GitHub Pages

• GitHub에서 제공하는 무료 정적 사이트 호스팅 서비스
• Swagger UI의 dist 폴더를 리포지토리에 업로드하고 GitHub Pages로 설정하면 간단히 배포할 수 있음

 

(2) Netlify

• 정적 웹사이트 배포에 특화된 플랫폼
• Swagger UI 파일을 업로드하면 자동으로 배포됨

 

(3) SwaggerHub

• Swagger의 공식 클라우드 서비스로, OpenAPI 스펙 작성 및 배포를 지원함

 

(4) Docker + Swagger UI

• Swagger UI Docker 이미지를 활용해 빠르게 로컬 또는 클라우드에서 API 문서를 배포할 수 있음

 

(5) Vercel

• Next.js 기반으로 알려진 플랫폼
• 정적 및 동적 사이트를 모두 지원하며 Swagger UI도 쉽게 배포할 수 있음

 

(6) Nginx 또는 Apache 서버

• Swagger UI 파일을 자체 서버(Nginx/Apache)에 업로드해 정적 웹페이지로 호스팅함

 

2. Github pages & Github actions를 이용한 Swagger 배포

 결론적으로 위 방법들 중 Github pages를 이용한 방법을 선택했다. 이유는 가장 쉬운 방법으로 보였기 때문이다.😅 배포 과정은 다음과 같다.

 

(1) 우선 아래 Github Repository에 들어가 Use this template 버튼을 통해 Repository를 생성한다. 작성자는 현재 프로젝트 Organization의 Repository에 swagger-github-pages라는 이름으로 생성했다.(해당 부분은 자유롭게 설정하면 된다.)

 

https://github.com/peter-evans/swagger-github-pages

GitHub - peter-evans/swagger-github-pages: How to host Swagger API documentation with GitHub Pages

 

• Use this template -> Create new repository

 

(2) 이후 Settings -> Pages에서 Branch를 master로 선택하고 경로를 /(root)로 선택한 후 Save로 저장한다. 

• Settings -> Pages -> Branch는 master -> 경로는 /(root) -> Save

 

(3) 현재 프로젝트에서 Swagger는 이미 구현되어 있기 때문에 해당 Swagger UI를 이용할 예정이다. 로컬 서버를 실행한 후, http://localhost:8080/v3/api-docs 에 접속한다. 

• 로컬 서버 실행 -> http://localhost:8080/v3/api-docs URL 접속

 

(4) 해당 URL에 있는 코드를 아래 링크를 통해 json 코드를 yaml 코드로 변환한다.

https://www.bairesdev.com/tools/json2yaml/

JSON to YAML Online Converter

 

(5) 변환한 코드를 생성했던 Repository의 swagger.yaml 파일에 그대로 복사 및 붙여넣기 한다.

• Repository -> swagger.yaml 파일에 복사 및 붙여넣기

 

 

(6) Repository에 Commit, Push 하면 정상적으로 배포가 완료된다!

 

https://pickable-v2.github.io/swagger-github-pages/

Swagger UI

 

어찌저찌 배포를 완료하긴 했지만,, 사실 Swagger 문서가 변경될 때마다 Repository에 지속적으로 업데이트 해줘야하는 번거로움이 있다. 자동으로 배포가 되도록 설정하는 방법을 다음 블로깅에 정리할 예정이다!

 

참고 링크

https://github.com/peter-evans/swagger-github-pages

GitHub - peter-evans/swagger-github-pages: How to host Swagger API documentation with GitHub Pages

https://velog.io/@gdhi/GitHub%EC%97%90-Swagger-API-%EB%AC%B8%EC%84%9C%EB%A5%BC-%EA%B3%B5%EC%9C%A0%ED%95%98%EA%B8%B0

GitHub에 Swagger API 문서를 공유하기