feat: add swagger docs (resolve #40)

routes/api/health.go

@@ -20,6 +20,12 @@ func (h *HealthApiHandler) RegisterRoutes(router *mux.Router) {
 	r.Methods(http.MethodGet).HandlerFunc(h.Get)
 }
 
+// @Summary Check the application's health status
+// @ID get-health
+// @Tags misc
+// @Produce plain
+// @Success 200 {string} string
+// @Router /health [get]
 func (h *HealthApiHandler) Get(w http.ResponseWriter, r *http.Request) {
 	var dbStatus int
 	if sqlDb, err := h.db.DB(); err == nil {

routes/api/heartbeat.go

@@ -43,6 +43,14 @@ func (h *HeartbeatApiHandler) RegisterRoutes(router *mux.Router) {
 	r.Methods(http.MethodPost).HandlerFunc(h.Post)
 }
 
+// @Summary Push a new heartbeat
+// @ID post-heartbeat
+// @Tags heartbeat
+// @Accept json
+// @Param heartbeat body models.Heartbeat true "A heartbeat"
+// @Security ApiKeyAuth
+// @Success 201
+// @Router /heartbeat [post]
 func (h *HeartbeatApiHandler) Post(w http.ResponseWriter, r *http.Request) {
 	var heartbeats []*models.Heartbeat
 	user := r.Context().Value(models.UserKey).(*models.User)

routes/api/summary.go

@@ -32,6 +32,17 @@ func (h *SummaryApiHandler) RegisterRoutes(router *mux.Router) {
 	r.Methods(http.MethodGet).HandlerFunc(h.Get)
 }
 
+// @Summary Retrieve a summary
+// @ID get-summary
+// @Tags summary
+// @Produce json
+// @Param interval query string false "Interval identifier" Enums(today, yesterday, week, month, year, 7_days, last_7_days, 30_days, last_30_days, 12_months, last_12_months, any)
+// @Param from query string false "Start date (e.g. '2021-02-07')"
+// @Param to query string false "End date (e.g. '2021-02-08')"
+// @Param recompute query bool false "Whether to recompute the summary from raw heartbeat or use cache"
+// @Security ApiKeyAuth
+// @Success 200 {object} models.Summary
+// @Router /summary [get]
 func (h *SummaryApiHandler) Get(w http.ResponseWriter, r *http.Request) {
 	summary, err, status := su.LoadUserSummary(h.summarySrvc, r)
 	if err != nil {