Support swagger API documentation

[seokho-son]

Swagger 를 통한 API 자동 문서화 기능 추가

• Swaggo (Automatically generate RESTful API documentation with Swagger 2.0 for Go)을 사용하여 API 문서를 생성할 수 있도록 코드를 제공함.
  • Swaggo 지원을 위해 ECHO를 ECHO4로 업그레이드 함. (ECHO4 가 최신 Stable임)
• API 문서가 Echo REST 서버에서 동작함.
  • 텀블벅 서버(REST) 실행 후, 접속: http://localhost:1323/swagger/index.html
• Namespace 관련 API 리소스에 대해 예제 코드 개발.
  • model 정리 필요
  • 애러코드 정리 필요

Golang의 ECHO를 위한 Swaggo 설치 및 사용 방법

• https://github.com/swaggo/echo-swagger 참고
  • cb-tumblebug/src 에서 ~/go/bin/swag init 을 수행하면, 소스코드 내의 annotation을 활용하여 swagger api 문서가 자동 생성됨
  • 텀블벅 소스빌드 및 서버 실행 필요
  • 텀블벅 서버(REST) 실행 후, 접속: http://localhost:1323/swagger/index.html

[seokho-son]

FYI: @powerkimhub

[powerkimhub]

@seokho-son @jihoon-seo

사람들이 postman vs swagger 사이를 고민하고 비교하던데,

• (1) 개인적으로 뭐가 더 적합해보이나요?
• (2) postman의 example 기능은 swagger 스타일에서는 제공할 필요가 없어지나요?
• (3) 아니면, swapper에 추가해 넣어야 하나요?

[seokho-son]

@seokho-son @jihoon-seo

사람들이 postman vs swagger 사이를 고민하고 비교하던데,

• (1) 개인적으로 뭐가 더 적합해보이나요?
• (2) postman의 example 기능은 swagger 스타일에서는 제공할 필요가 없어지나요?
• (3) 아니면, swapper에 추가해 넣어야 하나요?

@powerkimhub

일단 두 프로젝트의 주요 목적은 다음과 같은 것 같습니다.

• postman: API를 테스트하기 위한 클라언트와 API 문서의 실시간 공동 개발을 위한 프로젝트. (+API 문서 퍼블리싱)
• swagger: API의 문서화 및 퍼블리싱. (+간단한 클라이언트 기능)

(1) 개인적으로 뭐가 더 적합해보이나요?

• API를 테스트하기 위해서는 Postman이 편합니다. (환경변수 기능 등) 다만, 실제 사용해보니, API 동기화 문제 등 사소한 버그들이 발견되어 스트레스가 좀 있었습니다.
• Postman이 API의 업데이트를 정기적으로 따로 해줘야 하는 반면, Swagger는 코드를 개발하면서 바로바로 API의 업데이트가 수월합니다. (일부 API 문서의 일부는 자동생성)
• @jihoon-seo 님이 Swagger를 선호(API문서화의 글로벌 스탠다드?)합니다.. ㅎㅎ

(2) postman의 example 기능은 swagger 스타일에서는 제공할 필요가 없어지나요? 아니면, swagger에 추가해 넣어야 하나요?

• Swagger에서도 제공되는 것이 좋습니다.
• Swagger에서 Annotation code(코멘트)로 직접 입력해 두어야 Example 제공이 가능합니다. (수동이며, 실제값을 의미하는 것이 아님)

[powerkimhub]

@seokho-son 정보 공유 및 의견 감사합니다.