docs: include relay endpoint in swagger docs

2023-08-10 21:12:56 +03:00 · 2021-10-13 17:47:18 +02:00
parent 2c7977cf63
commit 3b96bd3723
15 changed files with 650 additions and 70 deletions
--- a/routes/api/diagnostics.go
+++ b/routes/api/diagnostics.go
@@ -41,7 +41,7 @@ func (h *DiagnosticsApiHandler) RegisterRoutes(router *mux.Router) {
 // @Param diagnostics body models.Diagnostics true "A single diagnostics object sent by WakaTime CLI"
 // @Security ApiKeyAuth
 // @Success 201
-// @Router /plugins/errors [post]
+// @Router /api/plugins/errors [post]
 func (h *DiagnosticsApiHandler) Post(w http.ResponseWriter, r *http.Request) {
 	var diagnostics models.Diagnostics

--- a/routes/api/health.go
+++ b/routes/api/health.go
@@ -25,7 +25,7 @@ func (h *HealthApiHandler) RegisterRoutes(router *mux.Router) {
 // @Tags misc
 // @Produce plain
 // @Success 200 {string} string
-// @Router /health [get]
+// @Router /api/health [get]
 func (h *HealthApiHandler) Get(w http.ResponseWriter, r *http.Request) {
 	var dbStatus int
 	if sqlDb, err := h.db.DB(); err == nil {
--- a/routes/api/heartbeat.go
+++ b/routes/api/heartbeat.go
@@ -60,7 +60,7 @@ func (h *HeartbeatApiHandler) RegisterRoutes(router *mux.Router) {
 // @Param heartbeat body models.Heartbeat true "A single heartbeat"
 // @Security ApiKeyAuth
 // @Success 201
-// @Router /heartbeat [post]
+// @Router /api/heartbeat [post]
 func (h *HeartbeatApiHandler) Post(w http.ResponseWriter, r *http.Request) {
 	user, err := routeutils.CheckEffectiveUser(w, r, h.userSrvc, "current")
 	if err != nil {
@@ -182,7 +182,7 @@ func constructSuccessResponse(n int) *heartbeatResponseVm {
 // @Param heartbeat body models.Heartbeat true "A single heartbeat"
 // @Security ApiKeyAuth
 // @Success 201
-// @Router /v1/users/{user}/heartbeats [post]
+// @Router /api/v1/users/{user}/heartbeats [post]
 func (h *HeartbeatApiHandler) postAlias1() {}

 // @Summary Push a new heartbeat
@@ -192,7 +192,7 @@ func (h *HeartbeatApiHandler) postAlias1() {}
 // @Param heartbeat body models.Heartbeat true "A single heartbeat"
 // @Security ApiKeyAuth
 // @Success 201
-// @Router /compat/wakatime/v1/users/{user}/heartbeats [post]
+// @Router /api/compat/wakatime/v1/users/{user}/heartbeats [post]
 func (h *HeartbeatApiHandler) postAlias2() {}

 // @Summary Push a new heartbeat
@@ -202,7 +202,7 @@ func (h *HeartbeatApiHandler) postAlias2() {}
 // @Param heartbeat body models.Heartbeat true "A single heartbeat"
 // @Security ApiKeyAuth
 // @Success 201
-// @Router /users/{user}/heartbeats [post]
+// @Router /api/users/{user}/heartbeats [post]
 func (h *HeartbeatApiHandler) postAlias3() {}

 // @Summary Push new heartbeats
@@ -212,7 +212,7 @@ func (h *HeartbeatApiHandler) postAlias3() {}
 // @Param heartbeat body []models.Heartbeat true "Multiple heartbeats"
 // @Security ApiKeyAuth
 // @Success 201
-// @Router /heartbeats [post]
+// @Router /api/heartbeats [post]
 func (h *HeartbeatApiHandler) postAlias4() {}

 // @Summary Push new heartbeats
@@ -222,7 +222,7 @@ func (h *HeartbeatApiHandler) postAlias4() {}
 // @Param heartbeat body []models.Heartbeat true "Multiple heartbeats"
 // @Security ApiKeyAuth
 // @Success 201
-// @Router /v1/users/{user}/heartbeats.bulk [post]
+// @Router /api/v1/users/{user}/heartbeats.bulk [post]
 func (h *HeartbeatApiHandler) postAlias5() {}

 // @Summary Push new heartbeats
@@ -232,7 +232,7 @@ func (h *HeartbeatApiHandler) postAlias5() {}
 // @Param heartbeat body []models.Heartbeat true "Multiple heartbeats"
 // @Security ApiKeyAuth
 // @Success 201
-// @Router /compat/wakatime/v1/users/{user}/heartbeats.bulk [post]
+// @Router /api/compat/wakatime/v1/users/{user}/heartbeats.bulk [post]
 func (h *HeartbeatApiHandler) postAlias6() {}

 // @Summary Push new heartbeats
@@ -242,5 +242,5 @@ func (h *HeartbeatApiHandler) postAlias6() {}
 // @Param heartbeat body []models.Heartbeat true "Multiple heartbeats"
 // @Security ApiKeyAuth
 // @Success 201
-// @Router /users/{user}/heartbeats.bulk [post]
+// @Router /api/users/{user}/heartbeats.bulk [post]
 func (h *HeartbeatApiHandler) postAlias7() {}
--- a/routes/api/summary.go
+++ b/routes/api/summary.go
@@ -42,7 +42,7 @@ func (h *SummaryApiHandler) RegisterRoutes(router *mux.Router) {
 // @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]
+// @Router /api/summary [get]
 func (h *SummaryApiHandler) Get(w http.ResponseWriter, r *http.Request) {
 	summary, err, status := su.LoadUserSummary(h.summarySrvc, r)
 	if err != nil {
--- a/routes/compat/shields/v1/badge.go
+++ b/routes/compat/shields/v1/badge.go
@@ -50,7 +50,7 @@ func (h *BadgeHandler) RegisterRoutes(router *mux.Router) {
 // @Param interval path string true "Interval to aggregate data for" Enums(today, yesterday, week, month, year, 7_days, last_7_days, 30_days, last_30_days, 12_months, last_12_months, any)
 // @Param filter path string true "Filter to apply (e.g. 'project:wakapi' or 'language:Go')"
 // @Success 200 {object} v1.BadgeData
-// @Router /compat/shields/v1/{user}/{interval}/{filter} [get]
+// @Router /api/compat/shields/v1/{user}/{interval}/{filter} [get]
 func (h *BadgeHandler) Get(w http.ResponseWriter, r *http.Request) {
 	intervalReg := regexp.MustCompile(intervalPattern)
 	entityFilterReg := regexp.MustCompile(entityFilterPattern)
--- a/routes/compat/wakatime/v1/all_time.go
+++ b/routes/compat/wakatime/v1/all_time.go
@@ -44,7 +44,7 @@ func (h *AllTimeHandler) RegisterRoutes(router *mux.Router) {
 // @Param user path string true "User ID to fetch data for (or 'current')"
 // @Security ApiKeyAuth
 // @Success 200 {object} v1.AllTimeViewModel
-// @Router /compat/wakatime/v1/users/{user}/all_time_since_today [get]
+// @Router /api/compat/wakatime/v1/users/{user}/all_time_since_today [get]
 func (h *AllTimeHandler) Get(w http.ResponseWriter, r *http.Request) {
 	values, _ := url.ParseQuery(r.URL.RawQuery)

--- a/routes/compat/wakatime/v1/projects.go
+++ b/routes/compat/wakatime/v1/projects.go
@@ -44,7 +44,7 @@ func (h *ProjectsHandler) RegisterRoutes(router *mux.Router) {
 // @Param q query string true "Query to filter projects by"
 // @Security ApiKeyAuth
 // @Success 200 {object} v1.ProjectsViewModel
-// @Router /compat/wakatime/v1/users/{user}/projects [get]
+// @Router /api/compat/wakatime/v1/users/{user}/projects [get]
 func (h *ProjectsHandler) Get(w http.ResponseWriter, r *http.Request) {
 	user, err := routeutils.CheckEffectiveUser(w, r, h.userSrvc, "current")
 	if err != nil {
--- a/routes/compat/wakatime/v1/stats.go
+++ b/routes/compat/wakatime/v1/stats.go
@@ -50,7 +50,7 @@ func (h *StatsHandler) RegisterRoutes(router *mux.Router) {
 // @Param range path string false "Range interval identifier" Enums(today, yesterday, week, month, year, 7_days, last_7_days, 30_days, last_30_days, 12_months, last_12_months, any)
 // @Security ApiKeyAuth
 // @Success 200 {object} v1.StatsViewModel
-// @Router /compat/wakatime/v1/users/{user}/stats/{range} [get]
+// @Router /api/compat/wakatime/v1/users/{user}/stats/{range} [get]
 func (h *StatsHandler) Get(w http.ResponseWriter, r *http.Request) {
 	var vars = mux.Vars(r)
 	var authorizedUser, requestedUser *models.User
--- a/routes/compat/wakatime/v1/statusbar.go
+++ b/routes/compat/wakatime/v1/statusbar.go
@@ -51,8 +51,8 @@ func (h *StatusBarHandler) RegisterRoutes(router *mux.Router) {
 // @Produce json
 // @Param user path string true "User ID to fetch data for (or 'current')"
 // @Security ApiKeyAuth
-// @Success 200 {object} v1.StatusBarViewModel
-// @Router /users/{user}/statusbar/today [get]
+// @Success 200 {object} StatusBarViewModel
+// @Router /api/users/{user}/statusbar/today [get]
 func (h *StatusBarHandler) Get(w http.ResponseWriter, r *http.Request) {
 	user, err := routeutils.CheckEffectiveUser(w, r, h.userSrvc, "current")
 	if err != nil {
--- a/routes/compat/wakatime/v1/summaries.go
+++ b/routes/compat/wakatime/v1/summaries.go
@@ -53,7 +53,7 @@ func (h *SummariesHandler) RegisterRoutes(router *mux.Router) {
 // @Param end query string false "End date (e.g. '2021-02-08')"
 // @Security ApiKeyAuth
 // @Success 200 {object} v1.SummariesViewModel
-// @Router /compat/wakatime/v1/users/{user}/summaries [get]
+// @Router /api/compat/wakatime/v1/users/{user}/summaries [get]
 func (h *SummariesHandler) Get(w http.ResponseWriter, r *http.Request) {
 	_, err := routeutils.CheckEffectiveUser(w, r, h.userSrvc, "current")
 	if err != nil {
--- a/routes/compat/wakatime/v1/users.go
+++ b/routes/compat/wakatime/v1/users.go
@@ -41,7 +41,7 @@ func (h *UsersHandler) RegisterRoutes(router *mux.Router) {
 // @Param user path string true "User ID to fetch (or 'current')"
 // @Security ApiKeyAuth
 // @Success 200 {object} v1.UserViewModel
-// @Router /compat/wakatime/v1/users/{user} [get]
+// @Router /api/compat/wakatime/v1/users/{user} [get]
 func (h *UsersHandler) Get(w http.ResponseWriter, r *http.Request) {
 	wakapiUser, err := routeutils.CheckEffectiveUser(w, r, h.userSrvc, "current")
 	if err != nil {
--- a/routes/relay/relay.go
+++ b/routes/relay/relay.go
@@ -73,3 +73,48 @@ func (h *RelayHandler) Any(w http.ResponseWriter, r *http.Request) {

 	p.ServeHTTP(w, r)
 }
+
+// @Summary Proxy an GET API request to another Wakapi instance
+// @ID relay-get
+// @Tags relay
+// @Param X-Target-URL header string true "Original URL to perform the request to"
+// @Failure 403 {string} string "Returned if request path is not whitelisted"
+// @Failure 502 {string} string "Returned if upstream host is down"
+// @Router /relay [get]
+func (h *RelayHandler) alias1() {}
+
+// @Summary Proxy an POST API request to another Wakapi instance
+// @ID relay-post
+// @Tags relay
+// @Param X-Target-URL header string true "Original URL to perform the request to"
+// @Failure 403 {string} string "Returned if request path is not whitelisted"
+// @Failure 502 {string} string "Returned if upstream host is down"
+// @Router /relay [post]
+func (h *RelayHandler) alias2() {}
+
+// @Summary Proxy an PUT API request to another Wakapi instance
+// @ID relay-put
+// @Tags relay
+// @Param X-Target-URL header string true "Original URL to perform the request to"
+// @Failure 403 {string} string "Returned if request path is not whitelisted"
+// @Failure 502 {string} string "Returned if upstream host is down"
+// @Router /relay [put]
+func (h *RelayHandler) alias3() {}
+
+// @Summary Proxy an PATCH API request to another Wakapi instance
+// @ID relay-patch
+// @Tags relay
+// @Param X-Target-URL header string true "Original URL to perform the request to"
+// @Failure 403 {string} string "Returned if request path is not whitelisted"
+// @Failure 502 {string} string "Returned if upstream host is down"
+// @Router /relay [patch]
+func (h *RelayHandler) alias4() {}
+
+// @Summary Proxy an DELETE API request to another Wakapi instance
+// @ID relay-delete
+// @Tags relay
+// @Param X-Target-URL header string true "Original URL to perform the request to"
+// @Failure 403 {string} string "Returned if request path is not whitelisted"
+// @Failure 502 {string} string "Returned if upstream host is down"
+// @Router /relay [delete]
+func (h *RelayHandler) alias5() {}