📝 feat: add swagger documentation and improve project structure

✨ feat: add API documentation with swagger and OpenAPI specs ♻️ refactor: reorganize server initialization and cleanup process 🔧 fix: update build paths in air.toml and Dockerfile The changes include: 1. Adding swagger documentation for API endpoints 2. Restructuring server initialization with proper cleanup 3. Moving main.go to root directory 4. Updating build configuration files 5. Adding API documentation endpoints and handlers
watzon · Nov 16, 2024 · 93ecaf7 · 93ecaf7
1 parent 63dbfab
commit 93ecaf7
Show file tree

Hide file tree

Showing 14 changed files with 373 additions and 136 deletions.
diff --git a/.air.toml b/.air.toml
@@ -5,7 +5,7 @@ tmp_dir = "tmp"
 [build]
   args_bin = []
   bin = "./tmp/main"
-  cmd = "go build -o ./tmp/main ./cmd/server"
+  cmd = "go build -o ./tmp/main ."
   delay = 1000
   exclude_dir = ["assets", "tmp", "vendor", "testdata"]
   exclude_file = []

diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,3 @@
-/docs/
 /lib/
 /bin/
 /uploads/

diff --git a/Dockerfile b/Dockerfile
@@ -6,7 +6,7 @@ COPY . .
 
 RUN mkdir -p /build/src/app
 
-RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o app/0x45 ./cmd/server/main.go
+RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o app/0x45 .
 
 FROM scratch
 

diff --git a/docs/docs.go b/docs/docs.go
@@ -0,0 +1,105 @@
+// 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": {},
+        "license": {
+            "name": "MIT",
+            "url": "https://github.com/watzon/0x45/blob/main/LICENSE"
+        },
+        "version": "{{.Version}}"
+    },
+    "host": "{{.Host}}",
+    "basePath": "{{.BasePath}}",
+    "paths": {
+        "/api/keys/request": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "API Key"
+                ],
+                "summary": "Request a new API key",
+                "operationId": "HandleRequestAPIKey",
+                "parameters": [
+                    {
+                        "description": "Request a new API key",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/services.APIKeyRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/services.APIKeyResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/services.APIKeyResponse"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "services.APIKeyRequest": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                }
+            }
+        },
+        "services.APIKeyResponse": {
+            "type": "object",
+            "properties": {
+                "key": {
+                    "type": "string"
+                },
+                "message": {
+                    "type": "string"
+                }
+            }
+        }
+    }
+}`
+
+// SwaggerInfo holds exported Swagger Info so clients can modify it
+var SwaggerInfo = &swag.Spec{
+	Version:          "1.0",
+	Host:             "localhost:3000",
+	BasePath:         "/",
+	Schemes:          []string{},
+	Title:            "0x45 API",
+	Description:      "API for 0x45",
+	InfoInstanceName: "swagger",
+	SwaggerTemplate:  docTemplate,
+	LeftDelim:        "{{",
+	RightDelim:       "}}",
+}
+
+func init() {
+	swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
+}
diff --git a/docs/swagger.json b/docs/swagger.json
@@ -0,0 +1,81 @@
+{
+    "swagger": "2.0",
+    "info": {
+        "description": "API for 0x45",
+        "title": "0x45 API",
+        "contact": {},
+        "license": {
+            "name": "MIT",
+            "url": "https://github.com/watzon/0x45/blob/main/LICENSE"
+        },
+        "version": "1.0"
+    },
+    "host": "localhost:3000",
+    "basePath": "/",
+    "paths": {
+        "/api/keys/request": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "API Key"
+                ],
+                "summary": "Request a new API key",
+                "operationId": "HandleRequestAPIKey",
+                "parameters": [
+                    {
+                        "description": "Request a new API key",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/services.APIKeyRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/services.APIKeyResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/services.APIKeyResponse"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "services.APIKeyRequest": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                }
+            }
+        },
+        "services.APIKeyResponse": {
+            "type": "object",
+            "properties": {
+                "key": {
+                    "type": "string"
+                },
+                "message": {
+                    "type": "string"
+                }
+            }
+        }
+    }
+}
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
@@ -0,0 +1,53 @@
+basePath: /
+definitions:
+  services.APIKeyRequest:
+    properties:
+      email:
+        type: string
+      name:
+        type: string
+    type: object
+  services.APIKeyResponse:
+    properties:
+      key:
+        type: string
+      message:
+        type: string
+    type: object
+host: localhost:3000
+info:
+  contact: {}
+  description: API for 0x45
+  license:
+    name: MIT
+    url: https://github.com/watzon/0x45/blob/main/LICENSE
+  title: 0x45 API
+  version: "1.0"
+paths:
+  /api/keys/request:
+    post:
+      consumes:
+      - application/json
+      operationId: HandleRequestAPIKey
+      parameters:
+      - description: Request a new API key
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/services.APIKeyRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/services.APIKeyResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/services.APIKeyResponse'
+      summary: Request a new API key
+      tags:
+      - API Key
+swagger: "2.0"
diff --git a/go.mod b/go.mod
@@ -28,6 +28,22 @@ require (
 	gorm.io/gorm v1.25.12
 )
 
+require (
+	github.com/KyleBanks/depth v1.2.1 // indirect
+	github.com/PuerkitoBio/purell v1.1.1 // indirect
+	github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
+	github.com/go-openapi/jsonpointer v0.19.5 // indirect
+	github.com/go-openapi/jsonreference v0.19.6 // indirect
+	github.com/go-openapi/spec v0.20.4 // indirect
+	github.com/go-openapi/swag v0.19.15 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/mailru/easyjson v0.7.6 // indirect
+	github.com/swaggo/files/v2 v2.0.0 // indirect
+	github.com/swaggo/swag v1.16.3 // indirect
+	golang.org/x/tools v0.27.0 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+)
+
 require (
 	github.com/alecthomas/chroma v0.10.0
 	github.com/andybalholm/brotli v1.1.1 // indirect
@@ -51,6 +67,7 @@ require (
 	github.com/dlclark/regexp2 v1.11.4 // indirect
 	github.com/fsnotify/fsnotify v1.8.0 // indirect
 	github.com/glebarez/go-sqlite v1.22.0 // indirect
+	github.com/gofiber/swagger v1.1.0
 	github.com/gofiber/template v1.8.3 // indirect
 	github.com/gofiber/utils v1.1.0 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect