[Spring Boot] swagger ui HTML문서로 출력하기

Back end rest api를 개발하면 api 스펙 문서를 어떻게 만들지 고민하게 된다. 그 대안중 하나로 널리 쓰이고 있는 swagger-ui 를 활용하는 방법이 있을 것이다.

 

swagger 형식에 맞게 doc 를 작성하고 서버를 실행하면 swagger 페이지를 볼 수 있다. 깔끔하게 rest api 스펙을 정리해서 보여주고 직접 api 테스트 및 결과 출력도 볼 수 있다.

 

그러나 여러 부서와 일을 하게 되면 산출물 공유시 문서가 필요할 경우가 있다. 서버 주소를 알려줄수도 있지만 오프라인으로 api 스펙 문서를 검토해야 할때는 별도의 문서 파일을 원하는 부서가 있을수 있다.

 

swagger 구현을 넘어서 swagger 공식 홈페이지에서는 swagger editor라는 tool을 제공해주고 있다. 온라인에서 swagger spec json 파일을 로딩하고 각종 아웃풋 파일을 생성할 수 있게 해준다.

 

swagger editor 주소는 다음과 같다

https://editor.swagger.io

 

직접 swagger ui html문서로 생성해보기

 

우선 swagger-ui를 서버에서 띄운후 아래 메인화면에 보이는 링크를 클릭한다.

 

그러면 브라우저에 swagger spec을 담은 전체 json 내용이 출력된다. 브라우저에서 우클릭하여 다른 이름으로 저장한다. (api-doc.json 등...)

 

json spec문서가 준비되었으면 swagger editor url로 진입 후 UI 화면에서 상단 File -> Import file 선택 -> 미리 저장해둔 json 파일을 선택한다.

 

swagger editor가 spec을 로딩한 후 ui로 렌더링 해준다. 우리의 목적은 html 파일로 출력하는게 목표 이므로 상단 Generate Client -> html2 를 선택한다.

 

swagger editor에서 html파일로 변환 후 zip파일을 생성해준다. zip 파일을 풀면 index.html 하나가 나올 것이다. 이것이 최종 변환된 api 스펙 문서이다.

 

열어보면 아래와 같이 깔끔하게 Controller 별 api 내용을 정리해서 보여준다.

 

Input/Output DTO 객체들도 깔끔하게 정리해서 문서로 뽑아준다.

 

swagger ui 문서 변환 관련해서 여러가지를 찾아봤지만 swagger editor의 html2 방식으로 변환하는 방법이 제일 좋은 거 같다.

 

-- The End --