diff --git a/README.md b/README.md index 15afa4c..a56245d 100644 --- a/README.md +++ b/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` diff --git a/src/v1_TeslaMateAPICars.go b/src/v1_TeslaMateAPICars.go index fbfdc25..f375ac7 100644 --- a/src/v1_TeslaMateAPICars.go +++ b/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 diff --git a/src/v1_TeslaMateAPICarsCharges.go b/src/v1_TeslaMateAPICarsCharges.go index f3d6880..14063cc 100644 --- a/src/v1_TeslaMateAPICarsCharges.go +++ b/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 diff --git a/src/v1_TeslaMateAPICarsChargesDetails.go b/src/v1_TeslaMateAPICarsChargesDetails.go index 7720677..3e3cfc9 100644 --- a/src/v1_TeslaMateAPICarsChargesDetails.go +++ b/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 diff --git a/src/v1_TeslaMateAPICarsCommand.go b/src/v1_TeslaMateAPICarsCommand.go index 4b80d7c..d185a3b 100644 --- a/src/v1_TeslaMateAPICarsCommand.go +++ b/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 diff --git a/src/v1_TeslaMateAPICarsDrives.go b/src/v1_TeslaMateAPICarsDrives.go index 70958d0..5b871eb 100644 --- a/src/v1_TeslaMateAPICarsDrives.go +++ b/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 diff --git a/src/v1_TeslaMateAPICarsDrivesDetails.go b/src/v1_TeslaMateAPICarsDrivesDetails.go index bb5e5c1..ca99684 100644 --- a/src/v1_TeslaMateAPICarsDrivesDetails.go +++ b/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 diff --git a/src/v1_TeslaMateAPICarsLogging.go b/src/v1_TeslaMateAPICarsLogging.go index 84a5ee3..4cdd381 100644 --- a/src/v1_TeslaMateAPICarsLogging.go +++ b/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 diff --git a/src/v1_TeslaMateAPICarsStatus.go b/src/v1_TeslaMateAPICarsStatus.go index e874c96..9f274a3 100644 --- a/src/v1_TeslaMateAPICarsStatus.go +++ b/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!") diff --git a/src/v1_TeslaMateAPICarsUpdates.go b/src/v1_TeslaMateAPICarsUpdates.go index ba8de28..21bb300 100644 --- a/src/v1_TeslaMateAPICarsUpdates.go +++ b/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 diff --git a/src/v1_TeslaMateAPIGlobalsettings.go b/src/v1_TeslaMateAPIGlobalsettings.go index 60c0e3b..a2ba6ff 100644 --- a/src/v1_TeslaMateAPIGlobalsettings.go +++ b/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 diff --git a/src/webserver.go b/src/webserver.go index 3f0871d..70a38d1 100644 --- a/src/webserver.go +++ b/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)}) }