Question about how to provide API documentation

[yunkon-kim]

다음 레퍼런스를 보면 GitHub pages를 활용하여 Swagger API documentation을 제공하는 방법을 2가지 제시하고 있습니다.

• How to host Swagger API documentation with GitHub Pages

1. 소스 코드 저장소와 github-pages 제공 관련 코드 저장소를 분리하여 관리 방법 (저장소 2개)
2. 소스 코드 저장소에 github-pages 제공 관련 코드를 함께 관리하는 방법 (저장소 1개)

두 가지 방법 중에서 저장소를 늘리지 않으면서 직관적으로 접근할 수 있는 2번 방법이 좋겠다는 생각이 듭니다.

이에 Cloud-Barista community 차원에서 2번 방법 적용을 제안 드리며, 이에 대한 의견을 듣고자 합니다.

• 적용 일정: 두 방법 모두 간단한 작업이라서 저장소 별로 적절한 시기에 적용 하시면 될 것 같습니다.

예시)

• CM-Beetle 2번 방법 적용 (확인해보니 mc-web-console, mc-iam-manager에도 적용되어 있었습니다.)
  • 저장소(소스 코드 및 github-pages 제공 관련 코드): https://github.com/cloud-barista/cm-beetle
    • github-page 제공 관련 code: index.html, /dist/*
    • Swagger API documentation (generated by swag init): /api/*
  • CM-Beetle's Swagger API documentation URL: https://cloud-barista.github.io/cm-beetle/

• CB-Tumblebug 1번 방법 적용:
  • 저장소(소스 코드): https://github.com/cloud-barista/cb-tumblebug
    • Swagger API documentation (generated by swag init): /src/api/rest/docs/*
  • 저장소(github-pages 제공 관련 코드): https://github.com/cloud-barista/cb-tumblebug-api-web
    • github-page 제공 관련 code: index.html, /dist/*
  • CB-Tumblebug's Swagger API documentation URL: https://cloud-barista.github.io/cb-tumblebug-api-web/

[seokho-son]

저장소 마다 API 문서 호스팅 방법(코드)까지 신경쓸 필요는 없다고 생각됩니다.
Swagger API dashboard (API 문서 공개용) 호스팅용 저장소를
공통적으로 하나만 활용하는 것은 어떠신가요? (모든 저장소에 대해서 1개)

기존 https://github.com/cloud-barista/cb-tumblebug-api-web 에서 제공하고 있는 호스팅 방법으로, 모든 저장소의 openapi spec 출력이 가능합니다. 아래와 같이 uri를 통해서 저장소별 api 문서의 위치를 지정할 수 있습니다.

단점은 URL path가 그대로 노출되는 경우, 다소 복잡해 보이긴 합니다.

CB-TB (main, v0.8.8)

• https://cloud-barista.github.io/cb-tumblebug-api-web/?url=https://raw.githubusercontent.com/cloud-barista/cb-tumblebug/main/src/api/rest/docs/swagger.yaml
• https://cloud-barista.github.io/cb-tumblebug-api-web/?url=https://raw.githubusercontent.com/cloud-barista/cb-tumblebug/v0.8.8/src/api/rest/docs/swagger.yaml

CM-Beetle (main, v0.1.0 - 아직없음)

• https://cloud-barista.github.io/cb-tumblebug-api-web/?url=https://raw.githubusercontent.com/cloud-barista/cm-beetle/main/api/swagger.yaml
• https://cloud-barista.github.io/cb-tumblebug-api-web/?url=https://raw.githubusercontent.com/cloud-barista/cm-beetle/v0.1.0/src/api/rest/docs/swagger.yaml

...

(참고로, 해당 API dashboard 를 보여주는 것은 사용자 편의성을 높여주는 방법일 뿐, openapi spec을 만족하는 경우에는 문서 파일만 노출하면 되고, 꼭 우리가 호스팅하여 dashboard로 보여줄 필요는 없기도 합니다.)

[yunkon-kim]

@seokho-son 의견 감사드립니다!

기존 호스팅 방법을 활용한다면, Base URL이 https://github.com/cloud-barista/cb-tumblebug-api-web이 되어있어 오해의 소지가 있어 보입니다. 그래서 한 저장소를 활용하는 방향으로 진행한다면, 기존 저장소 이름cb-tumblebug-api-web을 api 등으로 변경하는 것 정도가 필요해 보입니다.

[seokho-son]

명칭 변경에 동의합니다. 기존 저장소를 포크하여, 신규 공용 호스팅 저장소를 하나 만드는 것도 좋겠네요. (cloud-barista/api, cloud-barista/cloud-barista-api 등등)

참고로, v0.8.0 까지는 swagger를 통해서 api 문서를 제공하는 저장소는 일부여서,
https://github.com/cloud-barista/docs/blob/master/technical_docs/cloud-barista/API/CB-User_REST-API.md#-cloud-barista-user-rest-api-
저장소별로 다른 API 문서 주소 및 방식을 제공하였습니다.

[yunkon-kim]

Swagger API documentation 제공을 위해 아래와 같이 의견을 주신 것으로 이해하였습니다.

• 공통의 저장소 활용
• URL Path가 그대로 노출되는 경우 복잡해 보임
• API docs과 관련해서는 서브시스템별 정책 마련 및 제공

커뮤니티 차원의 Swagger API docs 제공, GitHub의 page hosting 정책, 복잡한 URl 이슈 등을 고려해서 추가 의견을 조금 더 받아보고 방향을 잡아보도록 하겠습니다.

서둘러 결정/적용해야하는 사안이 아니니 시간을 가지고 의견을 받도록 하겠습니다 😃

[yunkon-kim]

잠시 시간을 갖고 있었던 API documentation 관련 사항의 초안을 마련하였습니다.

• 저장소: https://github.com/cloud-barista/api
• GitHub page: https://cloud-barista.github.io/api/

위 페이지를 다음과 같이 구성하였습니다.

• query param으로 url이 전달 되지 않으면: 예) https://cloud-barista.github.io/api/
  • 저장소의 README를 출력합니다.
  • README에 서브시스템들의 저장소 및 API documentation 링크를 정리해 두었습니다.
• query param으로 url이 전달 되면: 예) https://cloud-barista.github.io/api/?url=https://raw.githubusercontent.com/cloud-barista/cb-tumblebug/main/src/api/rest/docs/swagger.yaml
  • Swagger UI에 해당 API 문서가 출력 됩니다.

[seokho-son]

@yunkon-kim

• 관련 프로젝트인 m-cmp 내부 저장소 api도 포함하면 될까요? :)
• 동일한 기능을 제공하는 https://cloud-barista.github.io/cb-tumblebug-api-web 는 차기릴리스까지 유지했다가(deprecated), 이후 제거(remove)하겠습니다.

[yunkon-kim]

@seokho-son
m-cmp 내부 저장소 API를 어디에 어떻게 포함할 것 인지에 대해 가볍게 이야기 나누어 보면 좋을 것 같습니다.
(적용은 금방 할 수 있습니다 ^^)