docs: swagger generated documentation

README.md

@@ -166,8 +166,8 @@ More detailed documentation of every endpoint will come..
 - POST `/api/v1/cars/:CarID/command/:Command`
 - GET `/api/v1/cars/:CarID/drives`
 - GET `/api/v1/cars/:CarID/drives/:DriveID`
-- PUT `/api/v1/cars/:CarID/logging/:Command`
 - GET `/api/v1/cars/:CarID/logging`
+- PUT `/api/v1/cars/:CarID/logging/:Command`
 - GET `/api/v1/cars/:CarID/status`
 - GET `/api/v1/cars/:CarID/updates`
 - POST `/api/v1/cars/:CarID/wake_up`

src/v1_TeslaMateAPICars.go

@@ -5,7 +5,25 @@ import (
 	_ "github.com/lib/pq"
 )
 
-// TeslaMateAPICarsV1 func
+// TeslaMateAPICarsV1List godoc
+// @Summary      TeslaMate cars endpoint
+// @Description  Get all cars from TeslaMate
+// @Description  Since no CarID is given, all cars will be returned.
+// @Tags         cars
+// @Router       /v1/cars/ [get]
+func TeslaMateAPICarsV1List() bool {
+	// this function is only used for the documentation
+	// it is not called in the code
+	return true
+}
+
+// TeslaMateAPICarsV1 godoc
+// @Summary      TeslaMate car-specific endpoint
+// @Description  Get a specific car by CarID from TeslaMate
+// @Description  The CarID is the ID of the car in the TeslaMate database.
+// @Tags         cars
+// @Param        CarID path int true "The CarID"
+// @Router       /v1/cars/{CarID} [get]
 func TeslaMateAPICarsV1(c *gin.Context) {
 
 	// define error messages

src/v1_TeslaMateAPICarsCharges.go

@@ -5,7 +5,15 @@ import (
 	_ "github.com/lib/pq"
 )
 
-// TeslaMateAPICarsChargesV1 func
+// TeslaMateAPICarsChargesV1 godoc
+// @Summary      TeslaMate charges endpoint
+// @Description  Get all charges for a specific car by CarID from TeslaMate
+// @Description  Since no ChargeID is given, all charges will be returned.
+// @Tags         charges
+// @Param        CarID path int true "The CarID"
+// @Param        page query int false "Page number for pagination" default(1)
+// @Param        show query int false "Number of results to show per page" default(100)
+// @Router       /v1/cars/{CarID}/charges [get]
 func TeslaMateAPICarsChargesV1(c *gin.Context) {
 
 	// define error messages

src/v1_TeslaMateAPICarsChargesDetails.go

@@ -7,7 +7,14 @@ import (
 	_ "github.com/lib/pq"
 )
 
-// TeslaMateAPICarsChargesDetailsV1 func
+// TeslaMateAPICarsChargesDetailsV1 godoc
+// @Summary      TeslaMate charge details endpoint
+// @Description  Get a specific charge by ChargeID from TeslaMate
+// @Description  The ChargeID is the ID of the charge in the TeslaMate database.
+// @Tags         charges
+// @Param        CarID path int true "The CarID"
+// @Param        ChargeID path int true "The ChargeID"
+// @Router       /v1/cars/{CarID}/charges/{ChargeID} [get]
 func TeslaMateAPICarsChargesDetailsV1(c *gin.Context) {
 
 	// define error messages

src/v1_TeslaMateAPICarsCommand.go

@@ -12,7 +12,39 @@ import (
 	_ "github.com/lib/pq"
 )
 
-// TeslaMateAPICarsCommandV1 func
+// TeslaMateAPICarsCommandV1List godoc
+// @Summary      TeslaMate commands-list endpoint
+// @Description  Get a list of allowed commands for a particular car by CarID from TeslaMate
+// @Tags         commands
+// @Param        CarID path int true "The CarID"
+// @Router       /v1/cars/{CarID}/command [get]
+func TeslaMateAPICarsCommandV1List() bool {
+	// this function is only used for the documentation
+	// it is not called in the code
+	return true
+}
+
+// TeslaMateAPICarsCommandV1WakeUp godoc
+// @Summary      TeslaMate wake up command endpoint
+// @Description  Wake up a specific car by CarID from TeslaMate
+// @Description  The CarID is the ID of the car in the TeslaMate database.
+// @Tags         commands
+// @Param        CarID path int true "The CarID"
+// @Router       /v1/cars/{CarID}/wake_up [post]
+func TeslaMateAPICarsCommandV1WakeUp(c *gin.Context) {
+	// this function is only used for the documentation
+	// it is not called in the code
+	TeslaMateAPICarsCommandV1(c)
+}
+
+// TeslaMateAPICarsCommandV1 godoc
+// @Summary      TeslaMate commands endpoint
+// @Description  Send a command to the Tesla API for a specific car by CarID
+// @Description  Documentation of how to construct the command can be found at https://tesla-api.timdorr.com/vehicle/commands
+// @Tags         commands
+// @Param        CarID path int true "The CarID"
+// @Param        command path string true "The command to send" extensions(x-example=flash_lights)
+// @Router       /v1/cars/{CarID}/command/{command} [post]
 func TeslaMateAPICarsCommandV1(c *gin.Context) {
 
 	// creating required vars

src/v1_TeslaMateAPICarsDrives.go

@@ -5,7 +5,15 @@ import (
 	_ "github.com/lib/pq"
 )
 
-// TeslaMateAPICarsDrivesV1 func
+// TeslaMateAPICarsDrivesV1 godoc
+// @Summary      TeslaMate drives endpoint
+// @Description  Get all drives for a specific car by CarID from TeslaMate
+// @Description  Since no DriveID is given, all drives will be returned.
+// @Tags         drives
+// @Param        CarID path int true "The CarID"
+// @Param        page query int false "Page number for pagination" default(1)
+// @Param        show query int false "Number of results to show per page" default(100)
+// @Router       /v1/cars/{CarID}/drives [get]
 func TeslaMateAPICarsDrivesV1(c *gin.Context) {
 
 	// define error messages

src/v1_TeslaMateAPICarsDrivesDetails.go

@@ -7,7 +7,14 @@ import (
 	_ "github.com/lib/pq"
 )
 
-// TeslaMateAPICarsDrivesDetailsV1 func
+// TeslaMateAPICarsDrivesDetailsV1 godoc
+// @Summary      TeslaMate drive details endpoint
+// @Description  Get a specific drive by DriveID from TeslaMate
+// @Description  The DriveID is the ID of the drive in the TeslaMate database.
+// @Tags         drives
+// @Param        CarID path int true "The CarID"
+// @Param        DriveID path int true "The DriveID"
+// @Router       /v1/cars/{CarID}/drives/{DriveID} [get]
 func TeslaMateAPICarsDrivesDetailsV1(c *gin.Context) {
 
 	// define error messages

src/v1_TeslaMateAPICarsLogging.go

@@ -12,7 +12,24 @@ import (
 	_ "github.com/lib/pq"
 )
 
-// TeslaMateAPICarsLoggingV1 func
+// TeslaMateAPICarsLoggingV1List godoc
+// @Summary      TeslaMate logging endpoint
+// @Tags         logging
+// @Param        CarID path int true "The CarID"
+// @Router       /v1/cars/{CarID}/logging [get]
+func TeslaMateAPICarsLoggingV1List() bool {
+	// this function is only used for the documentation
+	// it is not called in the code
+	return true
+}
+
+// TeslaMateAPICarsLoggingV1 godoc
+// @Summary      TeslaMate loggings endpoint
+// @Description  This endpoint is used to perform logging-commands towards TeslaMate web app
+// @Tags         logging
+// @Param        CarID path int true "The CarID"
+// @Param        command path string true "The command to send" extensions(x-example=flash_lights)
+// @Router       /v1/cars/{CarID}/logging/{command} [put]
 func TeslaMateAPICarsLoggingV1(c *gin.Context) {
 
 	// creating required vars

src/v1_TeslaMateAPICarsStatus.go

@@ -421,7 +421,13 @@ func (s *statusCache) newMessage(c mqtt.Client, msg mqtt.Message) {
 	}
 }
 
-// TeslaMateAPICarsStatusV1 func
+// TeslaMateAPICarsStatusV1 godoc
+// @Summary      TeslaMate status endpoint
+// @Description  Get status of a particular car by CarID from TeslaMate
+// @Description  The CarID is the ID of the car in the TeslaMate database.
+// @Tags         status
+// @Param        CarID path int true "The CarID"
+// @Router       /v1/cars/{CarID}/status [get]
 func (s *statusCache) TeslaMateAPICarsStatusV1(c *gin.Context) {
 	if s.mqttDisabled {
 		log.Println("[notice] TeslaMateAPICarsStatusV1 DISABLE_MQTT is set to true.. can not return status for car without mqtt!")

src/v1_TeslaMateAPICarsUpdates.go

@@ -5,7 +5,13 @@ import (
 	_ "github.com/lib/pq"
 )
 
-// TeslaMateAPICarsUpdatesV1 func
+// TeslaMateAPICarsUpdatesV1 godoc
+// @Summary      TeslaMate updates endpoint
+// @Description  Get updates of a particular car by CarID from TeslaMate
+// @Description  The CarID is the ID of the car in the TeslaMate database.
+// @Tags         updates
+// @Param        CarID path int true "The CarID"
+// @Router       /v1/cars/{CarID}/updates [get]
 func TeslaMateAPICarsUpdatesV1(c *gin.Context) {
 
 	// define error messages

src/v1_TeslaMateAPIGlobalsettings.go

@@ -7,7 +7,11 @@ import (
 	_ "github.com/lib/pq"
 )
 
-// TeslaMateAPIGlobalsettingsV1 func
+// TeslaMateAPIGlobalsettingsV1 godoc
+// @Summary      TeslaMate global settings endpoint
+// @Description  Get the global settings from TeslaMate
+// @Tags         globalsettings
+// @Router       /v1/globalsettings [get]
 func TeslaMateAPIGlobalsettingsV1(c *gin.Context) {
 
 	// define error messages

src/webserver.go

@@ -34,6 +34,21 @@ var (
 	allowList []string
 )
 
+// @title         TeslaMate API
+// @version       edge
+// @description   This is the API documentation for the TeslaMate API, a RESTful API to get data collected by self-hosted data logger TeslaMate in JSON.
+
+// @contact.name  Tobias Lindberg
+// @contact.url   https://github.com/tobiasehlert/teslamateapi
+
+// @license.name  MIT
+// @license.url   https://github.com/tobiasehlert/teslamateapi/blob/main/LICENSE
+
+// @schemes   http
+// @host      localhost:8080
+// @BasePath  /api
+// @Produce   json
+
 // main function
 func main() {
 	// setup of readyness endpoint code
@@ -151,7 +166,7 @@ func main() {
 		}
 
 		// /api/ping endpoint
-		api.GET("/ping", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"message": "pong"}) })
+		api.GET("/ping", pingz)
 
 		// health endpoints for kubernetes
 		api.GET("/healthz", healthz)
@@ -454,16 +469,49 @@ func checkArrayContainsString(s []string, e string) bool {
 	return false
 }
 
-// healthz is a liveness probe.
-func healthz(c *gin.Context) {
-	c.JSON(http.StatusOK, gin.H{"status": http.StatusText(http.StatusOK)})
+// PingResponse represents the response format for a ping response
+type PingResponse struct {
+	Message string `json:"message" example:"pong"`
 }
 
-// readyz is a readiness probe.
+// pingz godocs
+// @Summary      Ping endpoint
+// @Description  This endpoint is used to check response of the API
+// @Router       /ping [get]
+// @Success      200 {object} PingResponse "pong"
+func pingz(c *gin.Context) {
+	c.JSON(http.StatusOK, PingResponse{Message: "pong"})
+}
+
+// StatusOKResponse represents the response format of the health check
+type StatusOKResponse struct {
+	Status string `json:"status" example:"OK"`
+}
+
+// ErrorResponse represents a generic error structure
+type ErrorResponse struct {
+	Error string `json:"error" example:"Service Unavailable"`
+}
+
+// healthz godocs
+// @Summary      Health check endpoint
+// @Description  This endpoint is used to check if the API is running
+// @Router       /healthz [get]
+// @Success      200 {object} StatusOKResponse "OK"
+func healthz(c *gin.Context) {
+	c.JSON(http.StatusOK, StatusOKResponse{Status: http.StatusText(http.StatusOK)})
+}
+
+// readyz godocs
+// @Summary      Readiness check endpoint
+// @Description  This endpoint is used to check if the API is ready to serve requests
+// @Router       /readyz [get]
+// @Success      200 {object} StatusOKResponse "OK"
+// @Failure      503 {object} ErrorResponse "Service Unavailable"
 func readyz(c *gin.Context) {
 	if isReady == nil || !isReady.Load().(bool) {
-		c.JSON(http.StatusServiceUnavailable, gin.H{"error": http.StatusText(http.StatusServiceUnavailable)})
+		c.JSON(http.StatusServiceUnavailable, ErrorResponse{Error: http.StatusText(http.StatusServiceUnavailable)})
 		return
 	}
-	TeslaMateAPIHandleSuccessResponse(c, "webserver", gin.H{"status": http.StatusText(http.StatusOK)})
+	TeslaMateAPIHandleSuccessResponse(c, "webserver", StatusOKResponse{Status: http.StatusText(http.StatusOK)})
 }