feat(GIST-14): add api reference

gistsapp · Aug 1, 2024 · bb365a2 · bb365a2
1 parent 525a195
commit bb365a2
Show file tree

Hide file tree

Showing 6 changed files with 313 additions and 3 deletions.
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -0,0 +1,49 @@
+name: Deploy
+on:
+  push:
+    tags:
+      - "*"
+
+permissions:
+  contents: read
+
+jobs:
+  get_tag:
+    runs-on: ubuntu-latest
+    output:
+      tag: ${GITHUB_REF#refs/*/}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set output
+        id: vars
+        run: echo "tag=${GITHUB_REF#refs/*/}" >> $GITHUB_OUTPUT
+      - name: Check output
+        env:
+          RELEASE_VERSION: ${{ steps.vars.outputs.tag }}
+        run: |
+          echo $RELEASE_VERSION
+          echo ${{ steps.vars.outputs.tag }}
+  deploy:
+    name: deploy_project
+    runs-on: ubuntu-latest
+    needs: get_tag
+    env:
+      TAG: ${{ needs.get_tag.outputs.tag }}
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@v4
+        with:
+          repository: Courtcircuits/cluster
+          token: "${{ secrets.DEPLOYMENT_TOKEN }}"
+      - name: Update values.yaml
+        run: |
+          sudo add-apt-repository ppa:rmescandon/yq
+          sudo apt update
+          sudo apt install yq -y
+          cd projects/gists/gists
+          yq eval -i '.tag = env(TAG)' tag.yaml
+          git config --global user.name "GIST Bot"
+          git config --global user.email "[email protected]"
+          git add tag.yaml
+          git commit -m "api gist | ${{ env.TAG }} | ${{ github.event.head_commit.message }}"
+          git push
diff --git a/README.md b/README.md
@@ -1,5 +1,26 @@
 # Gists.app API - Code snippets and scripts safe
 
+## Usage
+
+Check the [API documentation](http://localhost:4000) for more information (for now this page is hosted locally, so please run the project before accessing the documentation).
+
+## Quick Start
+
+### Pre-requisites
+
+- Go (version 1.22+)
+- Air
+- docker compose
+- migrate
+
+### Onboarding script
+
+```bash
+docker compose up -d
+migrate -path=migrations -database "postgresql://postgres:[email protected]:5432/gists?sslmode=disable" -verbose up
+air
+```
+
 ## Installation
 
 1. Make sure that you have `air`

diff --git a/docs/openapi.json b/docs/openapi.json
@@ -0,0 +1,223 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "gist.app API reference",
+    "description": "Share and publish your scripts and code snippets in one curl.",
+    "version": "1.0.0"
+  },
+  "tags": [],
+  "paths": {
+    "/gists": {
+      "post": {
+        "summary": "Create a gist",
+        "deprecated": false,
+        "description": "",
+        "tags": [],
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": { "type": "string", "description": "name" },
+                  "content": { "type": "string" }
+                },
+                "required": ["name", "content"]
+              },
+              "example": {
+                "name": "temporibus sit amet",
+                "content": "Similique veniam illum laudantium sit. Officiis vitae esse accusantium. Deserunt hic distinctio dolores eos delectus enim reprehenderit sunt. Saepe doloremque iusto accusamus praesentium. Non deserunt aspernatur voluptate dolorem voluptas repellat quo nam modi. Nihil perferendis sapiente officiis quam voluptas ducimus tempora velit quaerat."
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Gist" }
+              }
+            }
+          }
+        },
+        "security": []
+      },
+      "get": {
+        "summary": "Get all gists",
+        "deprecated": false,
+        "description": "",
+        "tags": [],
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": { "$ref": "#/components/schemas/Gist" }
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/gists/{id}/name": {
+      "patch": {
+        "summary": "Update gist's name",
+        "deprecated": false,
+        "description": "",
+        "tags": [],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "",
+            "required": true,
+            "example": "1",
+            "schema": { "type": "string" }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": { "type": "string", "description": "name" }
+                },
+                "required": ["name"]
+              },
+              "example": { "name": "doloremque dolorum nobis" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": { "schema": { "type": "string" } }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/gists/{id}/content": {
+      "patch": {
+        "summary": "Update gist's content",
+        "deprecated": false,
+        "description": "",
+        "tags": [],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "",
+            "required": true,
+            "example": "1",
+            "schema": { "type": "string" }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": { "type": "string", "description": "name" }
+                },
+                "required": ["name"]
+              },
+              "example": { "content": "ezaeeza" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": { "schema": { "type": "string" } }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/gists/{id}": {
+      "get": {
+        "summary": "Get a gist",
+        "deprecated": false,
+        "description": "",
+        "tags": [],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "",
+            "required": true,
+            "example": "2",
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Gist" }
+              }
+            }
+          }
+        },
+        "security": []
+      },
+      "delete": {
+        "summary": "Delete a gist",
+        "deprecated": false,
+        "description": "",
+        "tags": [],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "",
+            "required": true,
+            "example": "1",
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": { "type": "object", "properties": {} }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Gist": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "description": "ID" },
+          "name": { "type": "string", "description": "name" },
+          "content": { "type": "string", "description": "content" }
+        },
+        "required": ["id", "name", "content"]
+      }
+    },
+    "securitySchemes": {}
+  },
+  "servers": []
+}
diff --git a/go.mod b/go.mod
@@ -5,6 +5,7 @@ go 1.22.5
 require github.com/gofiber/fiber/v2 v2.52.5
 
 require (
+	github.com/MarceloPetrucio/go-scalar-api-reference v0.0.0-20240521013641-ce5d2efe0e06 // indirect
 	github.com/andybalholm/brotli v1.0.5 // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
 	github.com/google/uuid v1.5.0 // indirect

diff --git a/go.sum b/go.sum
@@ -1,3 +1,5 @@
+github.com/MarceloPetrucio/go-scalar-api-reference v0.0.0-20240521013641-ce5d2efe0e06 h1:W4Yar1SUsPmmA51qoIRb174uDO/Xt3C48MB1YX9Y3vM=
+github.com/MarceloPetrucio/go-scalar-api-reference v0.0.0-20240521013641-ce5d2efe0e06/go.mod h1:/wotfjM8I3m8NuIHPz3S8k+CCYH80EqDT8ZeNLqMQm0=
 github.com/andybalholm/brotli v1.0.5 h1:8uQZIdzKmjc/iuPu7O2ioW48L81FgatrcpfFmiq/cCs=
 github.com/andybalholm/brotli v1.0.5/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

diff --git a/server/server.go b/server/server.go
@@ -1,9 +1,9 @@
 package server
 
 import (
-	"log"
-
+	"github.com/MarceloPetrucio/go-scalar-api-reference"
 	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/fiber/v2/log"
 	"github.com/gofiber/fiber/v2/middleware/cors"
 	"github.com/gofiber/fiber/v2/middleware/logger"
 )
@@ -25,8 +25,22 @@ func NewServer(listenAddr string) *Server {
 }
 
 func (s *Server) Ignite(routers ...DomainRouter) {
+
 	s.app.Get("/", func(c *fiber.Ctx) error {
-		return c.SendString("Hello, World! Don't fool me twice!")
+		htmlContent, err := scalar.ApiReferenceHTML(&scalar.Options{
+			SpecURL: "./docs/openapi.json",
+			Theme:   scalar.ThemeKepler,
+			CustomOptions: scalar.CustomOptions{
+				PageTitle: "Gists App API Reference",
+			},
+			DarkMode: true,
+		})
+
+		if err != nil {
+			log.Error(err)
+			return c.Status(500).SendString("Error generating API reference")
+		}
+		return c.Format(htmlContent)
 	})
 
 	s.app.Use(cors.New(cors.Config{