add OpenAPI specification and enhance gun management routes

Handlers/Guns/photos.go

@@ -4,13 +4,14 @@ import (
 	"bytes"
 	"context"
 	sql2 "database/sql"
+	"image/jpeg"
+	"net/http"
+	"strconv"
+
 	"git.siteworxpro.com/gun-manager/sql"
 	"git.siteworxpro.com/gun-manager/sql/db"
 	"github.com/labstack/echo/v4"
 	"github.com/nfnt/resize"
-	"image/jpeg"
-	"net/http"
-	"strconv"
 )
 
 func GetPhotoResize(c echo.Context) error {

main.go

@@ -2,15 +2,16 @@ package main
 
 import (
 	"flag"
+	"log"
+	"os"
+	"strings"
+
 	"git.siteworxpro.com/gun-manager/Handlers/Guns"
 	"git.siteworxpro.com/gun-manager/sql"
 	_ "github.com/golang-migrate/migrate/v4/source/file"
 	"github.com/labstack/echo/v4"
 	"github.com/labstack/echo/v4/middleware"
 	log2 "github.com/labstack/gommon/log"
-	"log"
-	"os"
-	"strings"
 )
 
 func main() {
@@ -68,17 +69,23 @@ func main() {
 		AllowHeaders: []string{"Origin", "Content-Type", "Accept"},
 	}))
 
+	// Serve static files from the "dist" directory
 	e.Static("/", "dist")
 
+	// Gun management routes
 	e.GET("/gun", Guns.Get)
 	e.PUT("/gun/:id", Guns.UpdateGun)
 	e.GET("/gun/:id", Guns.GetById)
 	e.DELETE("/gun/:id", Guns.DeleteById)
 	e.POST("/gun", Guns.Post)
+
+	// Photo download routes
 	e.GET("/gun/photo/:id/:filename", Guns.GetPhoto)
+	e.GET("/gun/photo/:id/:size/:filename", Guns.GetPhotoResize)
+
+	// Photo management routes
 	e.POST("/gun/photo/:id", Guns.PostPhoto)
 	e.DELETE("/gun/photo/:id", Guns.DeletePhoto)
-	e.GET("/gun/photo/:id/:size/:filename", Guns.GetPhotoResize)
 
 	e.Logger.Info("Starting server on port 8000")
 	e.Logger.Fatal(e.Start(":8000"))

openapi.yml

@@ -0,0 +1,350 @@
+openapi: 3.1.0
+info:
+  title: Gun API
+  version: 1.0.0
+  description: API for managing guns in a system.
+  contact:
+    name: Siteworx Pro
+    url: https://siteworxpro.com
+    email: websites@siteworxpro.com
+
+servers:
+  - url: http://localhost:8000
+    description: Local Server
+
+tags:
+  - name: Gun Management
+    description: Operations related to gun management
+  - name: Photo Management
+    description: Operations related to photo management
+
+paths:
+  /gun/{id}:
+    delete:
+      tags:
+        - Gun Management
+      operationId: deleteGunById
+      description: Deletes a gun by its unique identifier.
+      summary: Delete Gun by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Unique identifier for the gun
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '404':
+          description: Gun not found
+        '400':
+          description: Invalid ID supplied
+        '204':
+          description: Successfully deleted gun
+    put:
+      tags:
+        - Gun Management
+      operationId: updateGunById
+      description: Updates a gun by its unique identifier.
+      summary: Update Gun by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Unique identifier for the gun
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Gun'
+      responses:
+        '404':
+          description: Gun not found
+        '400':
+          description: Invalid ID supplied or invalid input data
+        '200':
+          description: Successfully updated gun'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Response'
+
+    get:
+      tags:
+        - Gun Management
+      operationId: getGunById
+      description: Retrieves a gun by its unique identifier.
+      summary: Get Gun by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Unique identifier for the gun
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '404':
+          description: Gun not found
+        '400':
+          description: Invalid ID supplied
+        '200':
+          description: A single gun object'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Response'
+
+  /gun:
+    post:
+      tags:
+        - Gun Management
+      operationId: createGun
+      description: Creates a new gun in the system.
+      summary: Create a new Gun
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Gun'
+      responses:
+        '201':
+          description: Successfully created gun'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Response'
+        '400':
+          description: Invalid input data
+    get:
+      tags:
+        - Gun Management
+      operationId: getAllGuns
+      description: Retrieves all guns in the system.
+      summary: Get all Guns
+      responses:
+        '200':
+          description: A list of guns'
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Response'
+
+  /gun/photo/{id}/{filename}:
+    get:
+      tags:
+        - Photo Management
+      operationId: getGunPhotoById
+      description: Retrieves a photo of a gun by its unique identifier.
+      summary: Get Gun Photo by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Unique identifier for the photo
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '404':
+          description: Photo not found
+        '400':
+          description: Invalid ID supplied
+        '200':
+          description: A single photo object
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+
+  /gun/photo/{id}/{size}/{filename}:
+    get:
+      tags:
+        - Photo Management
+      operationId: getGunPhotoByIdAndSize
+      description: Retrieves a photo of a gun by its unique identifier and size.
+      summary: Get Gun Photo by ID and Size
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Unique identifier for the photo
+          schema:
+            type: string
+            format: uuid
+            example: "uuid-1234-5678"
+        - name: size
+          in: path
+          required: true
+          description: Size of the photo
+          schema:
+            type: number
+            example: 1024
+        - name: filename
+          in: path
+          required: true
+          description: Name of the photo file
+          schema:
+            type: string
+            example: "gun_photo.jpg"
+      responses:
+        '404':
+          description: Photo not found
+        '400':
+          description: Invalid ID or size supplied
+        '200':
+          description: A single photo object with specified size
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+
+  /gun/photo/{id}:
+    delete:
+      tags:
+          - Photo Management
+      operationId: deleteGunPhotoById
+      description: Deletes a photo of a gun by its unique identifier.
+      summary: Delete Gun Photo by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Unique identifier for the photo
+          schema:
+              type: string
+              format: uuid
+      responses:
+        '404':
+          description: Photo not found
+        '400':
+          description: Invalid ID supplied
+        '204':
+          description: Successfully deleted photo
+    post:
+      tags:
+        - Photo Management
+      operationId: uploadGunPhoto
+      description: Uploads a photo for a gun.
+      summary: Upload Gun Photo
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Unique identifier for the gun
+          schema:
+            type: string
+            format: uuid
+            example: "uuid-1234-5678"
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                file:
+                  type: string
+                  format: binary
+                  description: The photo file to upload
+      responses:
+        '201':
+          description: Successfully uploaded photo'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Response'
+        '400':
+          description: Invalid input data or missing file
+        '404':
+          description: Gun not found
+
+components:
+  schemas:
+    Photo:
+      type: object
+      properties:
+        Id:
+          readOnly: true
+          type: string
+          description: Unique identifier for the photo
+          example: "uuid-1234-5678"
+          format: uuid
+        FileName:
+          required: true
+          type: string
+          description: The name of the photo file
+          example: "gun_photo.jpg"
+    Gun:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          type: string
+          description: Unique identifier for the gun
+          example: "uuid-1234-5678"
+          format: uuid
+        Make:
+          required: true
+          type: string
+          description: The make of the gun
+          example: "Smith & Wesson"
+        Model:
+          required: true
+          type: string
+          description: The model of the gun
+          example: "M&P Shield"
+        PurchaseAmount:
+          required: true
+          type: string
+          description: The purchase amount of the gun
+          example: "500.00"
+        ValueAmount:
+          required: true
+          type: string
+          description: The value of the gun
+          example: "10.00"
+        DatePurchased:
+          required: true
+          type: string
+          format: date
+          description: The date the gun was purchased
+          example: "2023-01-01"
+        SerialNumber:
+          required: true
+          type: string
+          description: The serial number of the gun
+          example: "SN123456789"
+        Notes:
+          required: true
+          type: string
+          description: Additional notes about the gun
+          example: "This is a test gun"
+        Photos:
+          readOnly: true
+          type: array
+          items:
+            $ref: '#/components/schemas/Photo'
+
+    Response:
+      type: object
+      properties:
+        status:
+          type: string
+          description: The status of the response
+        data:
+          type: object
+          oneOf:
+            - $ref: '#/components/schemas/Gun'
+            - type: array
+              items:
+                $ref: '#/components/schemas/Gun'