Swagger API 문서를 웹에 올려 링크 불러오기

Swagger UI로 생성한 API 문서는 프로젝트를 로컬에서 작업하는 경우 로컬에서만 확인할 수 있습니다.

그럼.. 로컬에서 작업한 개인 프로젝트의 API 문서를 다른 사람들이 볼 수 있게 하고 싶으면 어떡하죠?ㅠㅠ

 

개인 프로젝트의 GitHub README 파일에 API 명세를 링크하고 싶어서 이리저리 찾아보다.. 아주 쉬운 방법을 찾았습니다!

 

API 문서를 JSON 으로 저장

1. Swagger UI 로 생성한 API 문서 화면에 진입합니다. http://localhost:포트 번호/swagger-ui/index.html

예) http://localhost:8080/swagger-ui/index.html

 

2. API title 밑에 작은 글씨로 링크된 /v3/api-docs 를 클릭합니다.

(또는 http://localhost:포트 번호/v3/api-docs 로 진입하면 됩니다.)

 

그럼 JSON으로 변환된 데이터가 뜹니다.

 

3. 마우스 우클릭 - 다른 이름으로 저장 해줍니다.

 

SwaggerHub에 업로드

1. Swagger 공식 사이트에 접속해 Sign In 버튼을 눌러 회원가입을 진행합니다.

https://swagger.io/

 

2. 로그인하면 SwaggerHub 홈에 진입합니다. https://app.swaggerhub.com/home

왼편 상단 '+ Create New' 를 눌러 'Import and Document API'를 누릅니다.

Import API
Enter the path or URL to your API JSON or YAML spec, or browse to select a local file. Import to your personal account or change the Owner to any of your organizations.

Path or URL  [                                       ]   <Browse>
Owner           [                                       ] 
Project          [                                       ] 
Visibility        [                                       ] 

 

3. Path or URL 오른편 'Browse' 버튼을 눌러 저장했던 JSON 파일을 불러옵니다.

 

4. Owner에서 개인 계정을 선택합니다.

 

처음 가입했다면 Owner는 아마 2개가 뜰 텐데요..

가입하면 14일간 Enterprise 버전 trial을 제공하는데 자동으로 Organization 계정이 만들어집니다.

개인 계정(가입할 때 입력한 이름)을 눌러주셔야 14일 이후에도 계속 사용할 수 있습니다.

 

5. Visibility 는 Public 으로만 설정 가능합니다.

Private으로 설정하려면 유료 계정이어야 합니다.

 

6. 'Upload File' 버튼을 누릅니다.

 

7. Name 과 Version 을 입력하고, 'Import Definition' 버튼을 클릭합니다.

그러면 API가 웹에 업로드되고, 에디터 화면이 뜹니다!

 

Documentation 링크 가져오기

그런데 이 화면이 우리가 원하는 그 화면이 아닌데요..!ㅎㅎ

 

오른편 상단에 Export 버튼이 크게 보이고, 그 옆으로 아이콘들이 줄지어 있는데요.

딱 봐도 문서 처럼 생긴 아이콘에 마우스를 가져다 대면 'View Documentation'이라고 설명이 뜹니다.

그 버튼을 클릭해줍니다.

 

또는 https://app.swaggerhub.com/apis-docs/계정이름/api이름/api버전 으로 접속하시면 됩니다.

에디터 화면 url이 https://app.swaggerhub.com/api/계정이름/api이름/api버전 인데, 여기서 api 만 api-docs 로 바꿔주면 됩니다.

 

그러면 드디어 우리가 원하던 문서 화면을 얻을 수 있습니다!

 

해당 링크를 GitHub README 에 하이퍼링크로 삽입하면.. API 명세를 수기로 입력하거나, API 문서를 캡쳐해 불러오는 등의 작업을 하지 않을 수 있습니다..!!ㅎㅎ