Info: CB-TB sample server for Swagger page

[jihoon-seo]

• https://app.swaggerhub.com/apis-docs/cloud-barista-hub/cb-tumblebug/v0.2.0-20200729
• https://app.swaggerhub.com/apis/cloud-barista-hub/cb-tumblebug/v0.2.0-20200729

[Will be deprecated]

• http://132.145.80.18:1323/swagger/index.html
• Runs on Oracle Cloud Free Tier VM
• Will be updated occasionally
• Last updated: 2020-07-07
• username / password
• default / default
• (blank) / (blank)
• default-api-username / default-api-password

[issue-label-bot]

Issue-Label Bot is automatically applying the label bug to this issue, with a confidence of 0.56. Please mark this comment with 👍 or 👎 to give our bot feedback!

Links: app homepage, dashboard and code for this bot.

[powerkimhub]

@jihoon-seo @seokho-son

• Tumblebug 서버를 구동 시키지 않아도,
• API Docs 페이지를 제공할 수 있는 방법도 고민해봐야 겠습니다.
• 아울러, API Version별 docs 제공도.

[jihoon-seo]

@powerkimhub
잠시 찾아 보니, 이런 것들이 있습니다.

• How to generate offline Swagger API docs?
  • Swagger Editor - "Generate Client" menu - "HTML" or "Dynamic HTML"
  • Swagger Codegen - generate a static and dynamic HTML document
    • Swagger Editor leverages https://generator.swagger.io to generate code and generator.swagger.io (Swagger Generator) is part of the Swagger Codegen project.
  • Swagger2Markup - Example
  • pretty-swag

[powerkimhub]

@jihoon-seo
정보 감사합니다.

• 뭔가를 더 해줘야 될것 처럼 보이네요.
  . 이슈: 그들의 서비스 위(안)에서 Api docs page가 제공 되어야 하나? 그럼, postman publish와 유사한 이슈.

• 많은 부가 작업을 요한다면, 일단 Api Docs 전용 TB 서버를 상시 띄워 두는 것도 방법이겠어요.
  . 이슈: 어디다 띄우지? 항상 떠있을 까?

[seokho-son]

@jihoon-seo
정보 감사합니다.

• 뭔가를 더 해줘야 될것 처럼 보이네요.
  . 이슈: 그들의 서비스 위(안)에서 Api docs page가 제공 되어야 하나? 그럼, postman publish와 유사한 이슈.
• 많은 부가 작업을 요한다면, 일단 Api Docs 전용 TB 서버를 상시 띄워 두는 것도 방법이겠어요.
  . 이슈: 어디다 띄우지? 항상 떠있을 까?

@powerkimhub
현재 CB-TB에서 Swagger API 문서를 웹페이지로 띄우는 이유는 다음과 같습니다.

• TB 개발자가 개발시 API 기반의 테스팅 및 API 변경에 대한 검토도 쉽게 할 수 있도록 지원
• 디플로이된 TB가 있고 서비스하고 있는 경우, 해당 TB의 버전이 어떤 API를 제공하는지 (사내?) 에 공유하는 시나리오에서 활용
• API 문서를 외부에 퍼블리싱 하기 위한 목적은 아님

Swagger 기반 API 문서의 공개(퍼블리싱) 방식은 다음과 같을 것 같습니다.

1. Swagger 커뮤니티(?)가 제공하는 무료 호스팅 서비스를 이용
2. 외부에 별도 API 웹사이트용 서버 운영
3. Github Page에 빌드된 Swagger API 문서 웹페이지를 포함 (썸하우..)

[jihoon-seo]

"Swagger 커뮤니티(?)가 제공하는 무료 호스팅 서비스를 이용"

• https://app.swaggerhub.com/apis-docs/jihoon-seo/cb-tumblebug/v0.2.0-20200715

---

"외부에 별도 API 웹사이트용 서버 운영"

[Offline Swagger API doc samples]

[Swagger Editor]

• HTML: http://132.145.80.18:8080/v0.2.0-20200715/html-client/index.html
• HTML2: http://132.145.80.18:8080/v0.2.0-20200715/html2-client/index.html
• Dynamic HTML: http://132.145.80.18:8080/v0.2.0-20200715/dynamic-html-client/docs/index.html

[seokho-son]

• HTML: http://132.145.80.18:8080/v0.2.0-20200715/html-client/index.html
• HTML2: http://132.145.80.18:8080/v0.2.0-20200715/html2-client/index.html

해당 문서를 GitHub Page를 통해 호스팅하면 좋을 것 같습니다. (웹페이지로 보기, HTML 파일 다운로드)

[jihoon-seo]

저는 위의 옵션들 중에서는 SwaggerHub 을 통해 제공하는 것이 가장 가독성/편의성 등이 좋아 보입니다.

• https://app.swaggerhub.com/apis-docs/jihoon-seo/cb-tumblebug/v0.2.0-20200729

[SwaggerHub 관리 방법]

• SwaggerHub 에 새 API 버전 (예: v0.2.0-20200729) 객체를 만들고,
  개발 환경에서 swag i 명령을 통해 업데이트한 swagger.yaml 파일의 내용을 붙여넣기 합니다.
  (참고: https://app.swaggerhub.com/apis/jihoon-seo/cb-tumblebug/v0.2.0-20200729)
• 제가 SwaggerHub 에서 v0.2.0-20200715 버전과 v0.2.0-20200729 버전을 "Public" 상태로 두었기 때문에,
  로그인 없이도 위의 두 링크에 접근할 수 있는 것으로 보입니다.
  두 버전 모두 "Publish" 라는 기능은 아직 적용하지 않았습니다.

---

@powerkimhub

• Tumblebug 서버를 구동 시키지 않아도, API Docs 페이지를 제공 → 가능합니다.
• API Version별 docs 제공 → 가능합니다.
• 그들의 서비스 위(안)에서 Api docs page가 제공 되어야 하나? → 맞습니다.
  그럼, postman publish와 유사한 이슈. → 제가 해 보니 Postman 보다 직관적이고 편해 보입니다.

---

[위의 다른 옵션들의 문제점]

• HTML: http://132.145.80.18:8080/v0.2.0-20200715/html-client/index.html
  • SwaggerHub doc 은 각 항목이 접혀 있는 반면, 이 버전은 모든 항목이 펴져 (expanded) 있습니다.
  • Style (CSS) 이 적용되지 않는 부분들이 많이 보입니다.
• HTML2: http://132.145.80.18:8080/v0.2.0-20200715/html2-client/index.html
  • 좌측 메뉴의 가장 상단에 있는 항목인 nsNsIdResourcesImageDelete 를 예로 들면,
    이 항목은 REST API URL path가 /ns/{nsId}/resources/image 이고 method가 DELETE라서
    자동으로 nsNsIdResourcesImageDelete 라고 정해진 것인데,
    모든 API 항목들이 이런 식으로 되어 있어서 알아보기가 힘듭니다.
• Dynamic HTML: http://132.145.80.18:8080/v0.2.0-20200715/dynamic-html-client/docs/index.html
  • 위의 HTML2 와 동일한 문제가 있습니다.

[seokho-son]

@jihoon-seo
확인 및 테스트 공유에 감사 드립니다!! 🥇 👍

그렇다면, SwaggerHub가 제공하는 무료 호스팅 서비스를 사용하고,
향후에 특별한 의존성(SwaggerHub의 유료화 등)이 생긴다면, html 파일을 활용하여 다른 방식으로 호스팅하면 될 것 같습니다.

@dongjae @powerkimhub
Cloud-Barista 전체에 관련된 사항이므로 의견 공유 요청 드립니다.

[jihoon-seo]

Enhanced by @seokho-son 👍

CB-Tumblebug에서는 Swagger 를 통해, 소스코드에서 자동으로 API 문서를 생성하고 있습니다.

개발자를 위해서 해당 API 문서를 CB-Tumblebug의 서버를 통해 웹서비스 형태로 접속이 가능하도록 만들었습니다.

다만 기존의 웹서버는 소스코드를 빌드하는 개발자만 사용이 가능했었습니다.

사용자 측면에서도

"최신(master branch)" API 확인이 필요한 경우가 있으므로, 이를 GitHub가 [상시] 호스팅하도록 구성해 보았습니다.

• CB-Tumblebug API Web (Master branch) : https://cloud-barista.github.io/cb-tumblebug-api-web/

• 해당 웹서버를 개발을 위한 저장소: https://github.com/cloud-barista/cb-tumblebug-api-web