Add swagger docs for Backend

api/.env.sample

@@ -1,2 +1,2 @@
-FIREBASE_CONFIG=firebase_json_config_remove_all_whitespace_and_make_it_one_liner
+FIREBASE_CONFIG='firebase json config - uglify it to make it one liner'
 DB_CONN_STRING=host=localhost user=postgres password=password dbname=postgres port=5432

api/README.md

@@ -1,10 +1,64 @@
 # Ring Notify Backend
 
-## Running Docker Image
+A Go-based API server for sending Firebase Cloud Messaging (FCM) notifications to trigger calls.
+
+## Features
+
+- **User Management**: Create users with FCM tokens and get API keys
+- **FCM Notifications**: Send push notifications to trigger calls
+
+### Accessing Swagger UI
+
+When the server is running, you can access the interactive Swagger UI at:
+
+```
+http://localhost:1323/swagger/index.html
+```
+
+### API Endpoints
+
+- `GET /` - Health check endpoint
+- `POST /user/create` - Create a new user with FCM token
+- `POST /notify/call` - Send FCM notification (requires Bearer token)
+
+### Regenerating Documentation
+
+To regenerate the Swagger documentation after making changes to the API:
+
+```bash
+./generate-docs.sh
+```
+
+## Running the Application
+
+### Local Development
+
+1. Install dependencies:
+
+```bash
+go mod download
+```
+
+2. Set up environment variables (copy `.env.sample` to `.env` and configure)
+
+3. Run the server:
+
+```bash
+go run main.go
+```
+
+The server will start on `http://localhost:1323`
+
+### Docker
+
+#### Running Docker Image
 
 `docker container run --rm --env-file .env -p 1323:1323 ghcr.io/wtarit/ring-notify-backend:0.0.1`
 
-## Build Docker Image
+#### Build Docker Image
+
+Inside `api/` directory:
 
-Inside `api/` directory
-`docker build --tag ring-notify-backend .`
+```bash
+docker build --tag ring-notify-backend .
+```

api/docs/docs.go

@@ -0,0 +1,233 @@
+// Package docs Code generated by swaggo/swag. DO NOT EDIT
+package docs
+
+import "github.com/swaggo/swag"
+
+const docTemplate = `{
+    "schemes": {{ marshal .Schemes }},
+    "swagger": "2.0",
+    "info": {
+        "description": "{{escape .Description}}",
+        "title": "{{.Title}}",
+        "contact": {},
+        "version": "{{.Version}}"
+    },
+    "host": "{{.Host}}",
+    "basePath": "{{.BasePath}}",
+    "paths": {
+        "/": {
+            "get": {
+                "description": "Get the status of the API",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "healthcheck"
+                ],
+                "summary": "Health check",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.HealthCheckResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/notify/call": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Send a Firebase Cloud Messaging notification to trigger a call",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "notify"
+                ],
+                "summary": "Send FCM notification call",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "default": "Bearer your-api-key-here",
+                        "description": "Bearer token (API Key)",
+                        "name": "Authorization",
+                        "in": "header",
+                        "required": true
+                    },
+                    {
+                        "description": "Call request payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/notify.CallRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Called",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/notify.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/user/create": {
+            "post": {
+                "description": "Create a new user with FCM token and get API key",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "user"
+                ],
+                "summary": "Create a new user",
+                "parameters": [
+                    {
+                        "description": "User creation request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/user.CreateUserRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/user.CreateUserResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "models.HealthCheckResponse": {
+            "type": "object",
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "example": "active"
+                }
+            }
+        },
+        "notify.CallRequest": {
+            "type": "object",
+            "required": [
+                "text"
+            ],
+            "properties": {
+                "text": {
+                    "type": "string",
+                    "example": "Notification from ESP32"
+                }
+            }
+        },
+        "notify.ErrorResponse": {
+            "type": "object",
+            "properties": {
+                "reason": {
+                    "type": "string",
+                    "example": "Token no longer valid"
+                }
+            }
+        },
+        "user.CreateUserRequest": {
+            "type": "object",
+            "required": [
+                "fcmToken"
+            ],
+            "properties": {
+                "fcmToken": {
+                    "type": "string",
+                    "example": "fcm-token"
+                }
+            }
+        },
+        "user.CreateUserResponse": {
+            "type": "object",
+            "properties": {
+                "apiKey": {
+                    "type": "string",
+                    "example": "00000000-0000-0000-0000-000000000000"
+                },
+                "fcmKey": {
+                    "type": "string",
+                    "example": "fcm-token-example"
+                },
+                "fcmKeyUpdated": {
+                    "type": "string",
+                    "example": "2025-01-01T00:00:00Z"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "00000000-0000-0000-0000-000000000000"
+                },
+                "userCreated": {
+                    "type": "string",
+                    "example": "2025-01-01T00:00:00Z"
+                }
+            }
+        }
+    },
+    "securityDefinitions": {
+        "BearerAuth": {
+            "description": "Type \"Bearer\" followed by a space and JWT token.",
+            "type": "apiKey",
+            "name": "Authorization",
+            "in": "header"
+        }
+    }
+}`
+
+// SwaggerInfo holds exported Swagger Info so clients can modify it
+var SwaggerInfo = &swag.Spec{
+	Version:          "0.0.1",
+	Host:             "",
+	BasePath:         "",
+	Schemes:          []string{},
+	Title:            "Ring Notify API",
+	Description:      "API Specification for Ring Notify app.",
+	InfoInstanceName: "swagger",
+	SwaggerTemplate:  docTemplate,
+	LeftDelim:        "{{",
+	RightDelim:       "}}",
+}
+
+func init() {
+	swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
+}