From afa239379f7dc057dff4f1d69f82b9e70700c644 Mon Sep 17 00:00:00 2001
From: Ricardo Lopes <ricardo.lopes@doutorfinancas.pt>
Date: Wed, 23 Aug 2023 17:43:12 +0100
Subject: [PATCH] feat: adds documentation (#20)

- Creates Swagger docs (closes #19)
- Adds example for patch /short/:id
- Minor fixes on documentation
- Enables github pages with docs
---
 Makefile          |   5 +
 README.md         |  43 +++-
 api/preview.go    |  19 +-
 api/shortener.go  |  60 +++++-
 docs/favicon.ico  | Bin 0 -> 1150 bytes
 docs/index.html   |  30 +++
 docs/swagger.json | 487 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/swagger.yaml | 321 ++++++++++++++++++++++++++++++
 main.go           |   6 +
 9 files changed, 964 insertions(+), 7 deletions(-)
 create mode 100644 docs/favicon.ico
 create mode 100644 docs/index.html
 create mode 100644 docs/swagger.json
 create mode 100644 docs/swagger.yaml

diff --git a/Makefile b/Makefile
index be8d67b..2ad3ad0 100644
--- a/Makefile
+++ b/Makefile
@@ -76,3 +76,8 @@ migration/force:
 .PHONY: image-push
 image-push:
 	@build-tools/tag.sh
+
+.PHONY: docs
+docs:
+	@swag init --parseDependency --parseInternal --parseDepth 1
+	@rm docs/docs.go
diff --git a/README.md b/README.md
index 7d20987..19ea7dd 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,8 @@ you can use either `cockroach` or `postgres` as value for the `DB_ADAPTOR`
 
 If you want to use `cockroach`, you can create a free account [here](https://cockroachlabs.cloud/)
 
+Bellow are a few examples of how to use the API. You can find the documentation [here](https://doutorfinancas.github.io/pun-sho/)
+
 ### Create a short link
 ```bash
 read -r -d '' BODY <<EOF
@@ -84,6 +86,43 @@ This would render an answer like:
 }
 ```
 
+### Edit a short link
+It's also possible to edit a shortlink, by using the PATCH method
+
+```bash
+read -r -d '' BODY <<EOF
+{                
+  "link": "https://www.google.pt/",
+  "TTL": "2023-03-25T23:59:59Z",
+  "redirection_limit": 5,
+  "cancel": false,
+}
+EOF
+
+curl -XPATCH http://localhost:8080/api/v1/short/4b677dfe-e17a-46e7-9cd2-25a45e8cb19c \
+  -H 'token: ThisIsA5uper$ecureAPIToken' \
+  -H 'Content-Type: application/json' \
+  -d $BODY
+```
+
+The response is equal to the POST one:
+```json
+{
+  "id":"4b677dfe-e17a-46e7-9cd2-25a45e8cb19c",
+  "link":"https://www.google.pt/",
+  "TTL":"2023-03-25T23:59:59Z",
+  "redirection_limit": 5,
+  "created_at":"2023-03-20T10:50:38.399449Z",
+  "deleted_at":null,
+  "accesses":null,
+  "qr_code": "data:image/png;base64,ASfojih134kjhas9f8798134lk2fasf...",
+  "short_link":"https://env.configured.domain/s/SEdeyZByeP",
+  "visits":0,
+  "redirects":0
+}
+```
+
+### Preview QR code
 If you want to preview the QR code only, you can use the preview endpoint with the same body as above
 No TTL exists in that endpoint though (as its only preview mode), and the link is exactly the one you sent
 ```bash
@@ -214,5 +253,5 @@ we will be releasing 0.X until we bind a contract to the API
   - [ ] Dashboard with overview
   - [ ] Ability to track a specific link data
   - [ ] Show list of links with filters (by date range, status)
-- [ ] Allow better security (oauth2 or even simple jwt)
-- [ ] Add GitHub pages with openapi/swagger definition
+- [ ] Allow better security (variable API Key, oauth2 or even simple jwt)
+- [X] Add GitHub pages with openapi/swagger definition #19
diff --git a/api/preview.go b/api/preview.go
index 7bfd25b..a1e456a 100644
--- a/api/preview.go
+++ b/api/preview.go
@@ -21,15 +21,26 @@ func NewPreviewHandler(qrSvc *service.QRCodeService) HTTPHandler {
 }
 
 func (h *previewHandler) Routes(rg *gin.RouterGroup) {
-	rg.POST("", h.CreateLink)
-	rg.POST("/", h.CreateLink)
+	rg.POST("", h.CreatePreview)
+	rg.POST("/", h.CreatePreview)
 }
 
 func (h *previewHandler) Group() *string {
 	return str.ToStringNil("preview")
 }
 
-func (h *previewHandler) CreateLink(c *gin.Context) {
+// CreatePreview godoc
+// @Tags Preview
+// @Summary Creates a QR Code preview for a given url
+// @Schemes
+// @Description Creates a QR Code preview for a given url
+// @Param token header string false "Authorization token"
+// @Param request body request.GeneratePreview true "Request"
+// @Produce json
+// @Success 201 {object} response.GeneratePreviewResponse "response"
+// @Failure 400 {object} response.FailureResponse "error"
+// @Router /preview [post]
+func (h *previewHandler) CreatePreview(c *gin.Context) {
 	m := &request.GeneratePreview{}
 	err := c.BindJSON(m)
 
@@ -44,7 +55,7 @@ func (h *previewHandler) CreateLink(c *gin.Context) {
 	if err != nil {
 		c.JSON(
 			http.StatusBadRequest,
-			response.NewFailure("kaput, no save"),
+			response.NewFailure("failed to generate preview"),
 		)
 		return
 	}
diff --git a/api/shortener.go b/api/shortener.go
index 14d8316..209d169 100644
--- a/api/shortener.go
+++ b/api/shortener.go
@@ -34,6 +34,17 @@ func (h *shortenerHandler) Group() *string {
 	return str.ToStringNil("short")
 }
 
+// GetLinkInformation godoc
+// @Tags Short
+// @Summary get your shortlink information
+// @Schemes
+// @Description retrieves full information for the give shortlink
+// @Param token header string false "Authorization token"
+// @Param id path string true "ShortLink ID"
+// @Success 200 {object} entity.Shorty "response"
+// @Failure 400 {object} response.FailureResponse "error"
+// @Failure 404 {object} response.FailureResponse "not found"
+// @Router /short/{id} [get]
 func (h *shortenerHandler) GetLinkInformation(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {
@@ -52,6 +63,16 @@ func (h *shortenerHandler) GetLinkInformation(c *gin.Context) {
 	c.JSON(http.StatusOK, shorty)
 }
 
+// ListLinks godoc
+// @Tags Short
+// @Summary Lists your shorlinks
+// @Schemes
+// @Description Lists all the shortlinks available
+// @Param token header string false "Authorization token"
+// @Produce json
+// @Success 200 {object} []entity.Shorty "response"
+// @Failure 400 {object} response.FailureResponse "error"
+// @Router /short [get]
 func (h *shortenerHandler) ListLinks(c *gin.Context) {
 	limitStr := c.Query("limit")
 	offsetStr := c.Query("offset")
@@ -77,6 +98,17 @@ func (h *shortenerHandler) ListLinks(c *gin.Context) {
 	c.JSON(http.StatusOK, links)
 }
 
+// CreateLink godoc
+// @Tags Short
+// @Summary Creates a shortlink for a given url
+// @Schemes
+// @Description Creates a shortlink for a given url, optionally setting a ttl and a redirection limit
+// @Param token header string false "Authorization token"
+// @Param request body request.CreateShorty true "Request"
+// @Produce json
+// @Success 201 {object} entity.Shorty "response"
+// @Failure 400 {object} response.FailureResponse "error"
+// @Router /short [post]
 func (h *shortenerHandler) CreateLink(c *gin.Context) {
 	m := &request.CreateShorty{}
 	err := c.BindJSON(m)
@@ -100,6 +132,19 @@ func (h *shortenerHandler) CreateLink(c *gin.Context) {
 	c.JSON(http.StatusCreated, s)
 }
 
+// EditLink godoc
+// @Tags Short
+// @Summary Edits a shortlink
+// @Schemes
+// @Description Edits a shortlink, allowing to set TTL, cancel the link or change the redirection limit or associated link
+// @Param token header string false "Authorization token"
+// @Param id path string true "ShortLink ID"
+// @Param request body request.UpdateShorty true "Request"
+// @Produce json
+// @Success 200 {object} entity.Shorty "response"
+// @Failure 400 {object} response.FailureResponse "error"
+// @Failure 404 {object} response.FailureResponse "not found"
+// @Router /short/{id} [patch]
 func (h *shortenerHandler) EditLink(c *gin.Context) {
 	id := c.Param("id")
 	m := &request.UpdateShorty{}
@@ -130,6 +175,19 @@ func (h *shortenerHandler) EditLink(c *gin.Context) {
 	c.JSON(http.StatusOK, updatedShorty)
 }
 
+// RemoveLink godoc
+// @Tags Short
+// @Summary Deletes a shortlink
+// @Schemes
+// @Description Deletes a shortlink
+// @Param token header string false "Authorization token"
+// @Param id path string true "ShortLink ID"
+// @Param request body request.UpdateShorty true "Request"
+// @Produce json
+// @Success 204 string false ""
+// @Failure 400 {object} response.FailureResponse "error"
+// @Failure 404 {object} response.FailureResponse "not found"
+// @Router /short/{id} [delete]
 func (h *shortenerHandler) RemoveLink(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {
@@ -146,5 +204,5 @@ func (h *shortenerHandler) RemoveLink(c *gin.Context) {
 			response.NewFailure("kaput, no delete"),
 		)
 	}
-	c.JSON(http.StatusOK, nil)
+	c.JSON(http.StatusNoContent, nil)
 }
diff --git a/docs/favicon.ico b/docs/favicon.ico
new file mode 100644
index 0000000000000000000000000000000000000000..8511698970146391de63c1d4418124ddf523ab2d
GIT binary patch
literal 1150
zcmZQzU<5(|0R|wcz>vYhz#zuJz@P!dKp~(AL>x#lFaYI-0=T%&`#-7fG|>@u0AY|`
z7>0>qqhaR5)RIF_t2L{{rSCrw;F2Ro9Hbuvh*1kt^WbDVSpB8-esFy-{a^tgLCCCU
zm*>Kig4Mz~NDM+|pv!}_!o)!AkI#<5`7m)(XpkA#cO+3{1}XLtQVU8)gw)`Yho!-R
Zr2hkR8VLUe;*X$Q$4J;U4L~(8eE{q4?Xv&?

literal 0
HcmV?d00001

diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 0000000..d24a219
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,30 @@
+<html>
+<head>
+    <!-- Load the latest Swagger UI code and style from npm using unpkg.com -->
+    <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
+    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css"/>
+    <title>Pun-Sho API</title>
+    <link rel="shortcut icon" href="/pun-sho/favicon.ico">
+</head>
+<body>
+<div id="swagger-ui"></div> <!-- Div to hold the UI component -->
+<script>
+    window.onload = function () {
+        // Begin Swagger UI call region
+        const ui = SwaggerUIBundle({
+            url: "swagger.json", //Location of Open API spec in the repo
+            dom_id: '#swagger-ui',
+            deepLinking: true,
+            presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIBundle.SwaggerUIStandalonePreset
+            ],
+            plugins: [
+                SwaggerUIBundle.plugins.DownloadUrl
+            ],
+        })
+        window.ui = ui
+    }
+</script>
+</body>
+</html>
diff --git a/docs/swagger.json b/docs/swagger.json
new file mode 100644
index 0000000..8abf1d4
--- /dev/null
+++ b/docs/swagger.json
@@ -0,0 +1,487 @@
+{
+    "swagger": "2.0",
+    "info": {
+        "description": "Create your shortlinks with QRCodes and more!",
+        "title": "Pun Sho API",
+        "contact": {},
+        "version": "0.2"
+    },
+    "basePath": "/api/v1",
+    "paths": {
+        "/preview": {
+            "post": {
+                "description": "Creates a QR Code preview for a given url",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Preview"
+                ],
+                "summary": "Creates a QR Code preview for a given url",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Authorization token",
+                        "name": "token",
+                        "in": "header"
+                    },
+                    {
+                        "description": "Request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/request.GeneratePreview"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "response",
+                        "schema": {
+                            "$ref": "#/definitions/response.GeneratePreviewResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "error",
+                        "schema": {
+                            "$ref": "#/definitions/response.FailureResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/short": {
+            "get": {
+                "description": "Lists all the shortlinks available",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Short"
+                ],
+                "summary": "Lists your shorlinks",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Authorization token",
+                        "name": "token",
+                        "in": "header"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "response",
+                        "schema": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/entity.Shorty"
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "error",
+                        "schema": {
+                            "$ref": "#/definitions/response.FailureResponse"
+                        }
+                    }
+                }
+            },
+            "post": {
+                "description": "Creates a shortlink for a given url, optionally setting a ttl and a redirection limit",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Short"
+                ],
+                "summary": "Creates a shortlink for a given url",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Authorization token",
+                        "name": "token",
+                        "in": "header"
+                    },
+                    {
+                        "description": "Request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/request.CreateShorty"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "response",
+                        "schema": {
+                            "$ref": "#/definitions/entity.Shorty"
+                        }
+                    },
+                    "400": {
+                        "description": "error",
+                        "schema": {
+                            "$ref": "#/definitions/response.FailureResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/short/{id}": {
+            "get": {
+                "description": "retrieves full information for the give shortlink",
+                "tags": [
+                    "Short"
+                ],
+                "summary": "get your shortlink information",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Authorization token",
+                        "name": "token",
+                        "in": "header"
+                    },
+                    {
+                        "type": "string",
+                        "description": "ShortLink ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "response",
+                        "schema": {
+                            "$ref": "#/definitions/entity.Shorty"
+                        }
+                    },
+                    "400": {
+                        "description": "error",
+                        "schema": {
+                            "$ref": "#/definitions/response.FailureResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "not found",
+                        "schema": {
+                            "$ref": "#/definitions/response.FailureResponse"
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "description": "Deletes a shortlink",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Short"
+                ],
+                "summary": "Deletes a shortlink",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Authorization token",
+                        "name": "token",
+                        "in": "header"
+                    },
+                    {
+                        "type": "string",
+                        "description": "ShortLink ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/request.UpdateShorty"
+                        }
+                    }
+                ],
+                "responses": {
+                    "204": {
+                        "description": "No Content",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "400": {
+                        "description": "error",
+                        "schema": {
+                            "$ref": "#/definitions/response.FailureResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "not found",
+                        "schema": {
+                            "$ref": "#/definitions/response.FailureResponse"
+                        }
+                    }
+                }
+            },
+            "patch": {
+                "description": "Edits a shortlink, allowing to set TTL, cancel the link or change the redirection limit or associated link",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Short"
+                ],
+                "summary": "Edits a shortlink",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Authorization token",
+                        "name": "token",
+                        "in": "header"
+                    },
+                    {
+                        "type": "string",
+                        "description": "ShortLink ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/request.UpdateShorty"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "response",
+                        "schema": {
+                            "$ref": "#/definitions/entity.Shorty"
+                        }
+                    },
+                    "400": {
+                        "description": "error",
+                        "schema": {
+                            "$ref": "#/definitions/response.FailureResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "not found",
+                        "schema": {
+                            "$ref": "#/definitions/response.FailureResponse"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "entity.Meta": {
+            "type": "object",
+            "properties": {
+                "meta_collection": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/entity.MetaValues"
+                    }
+                }
+            }
+        },
+        "entity.MetaValues": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string"
+                },
+                "values": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
+        "entity.Shorty": {
+            "type": "object",
+            "properties": {
+                "TTL": {
+                    "type": "string"
+                },
+                "accesses": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/entity.ShortyAccess"
+                    }
+                },
+                "created_at": {
+                    "type": "string"
+                },
+                "deleted_at": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "link": {
+                    "type": "string"
+                },
+                "qr_code": {
+                    "type": "string"
+                },
+                "redirection_limit": {
+                    "type": "integer"
+                },
+                "redirects": {
+                    "type": "integer"
+                },
+                "short_link": {
+                    "type": "string"
+                },
+                "visits": {
+                    "type": "integer"
+                }
+            }
+        },
+        "entity.ShortyAccess": {
+            "type": "object",
+            "properties": {
+                "browser": {
+                    "type": "string"
+                },
+                "created_at": {
+                    "type": "string"
+                },
+                "extra": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "ip": {
+                    "type": "string"
+                },
+                "meta": {
+                    "$ref": "#/definitions/entity.Meta"
+                },
+                "os": {
+                    "type": "string"
+                },
+                "status": {
+                    "type": "string"
+                },
+                "user_agent": {
+                    "type": "string"
+                }
+            }
+        },
+        "request.CreateShorty": {
+            "type": "object",
+            "properties": {
+                "TTL": {
+                    "type": "string"
+                },
+                "link": {
+                    "type": "string"
+                },
+                "qr_code": {
+                    "$ref": "#/definitions/request.QRCode"
+                },
+                "redirection_limit": {
+                    "type": "integer"
+                }
+            }
+        },
+        "request.GeneratePreview": {
+            "type": "object",
+            "properties": {
+                "link": {
+                    "type": "string"
+                },
+                "qr_code": {
+                    "$ref": "#/definitions/request.QRCode"
+                }
+            }
+        },
+        "request.QRCode": {
+            "type": "object",
+            "properties": {
+                "background_color": {
+                    "type": "string"
+                },
+                "border_width": {
+                    "type": "integer"
+                },
+                "create": {
+                    "type": "boolean"
+                },
+                "foreground_color": {
+                    "type": "string"
+                },
+                "logo": {
+                    "type": "string"
+                },
+                "shape": {
+                    "type": "string"
+                },
+                "width": {
+                    "type": "integer"
+                }
+            }
+        },
+        "request.UpdateShorty": {
+            "type": "object",
+            "properties": {
+                "TTL": {
+                    "type": "string"
+                },
+                "cancel": {
+                    "type": "boolean"
+                },
+                "link": {
+                    "type": "string"
+                },
+                "redirection_limit": {
+                    "type": "integer"
+                }
+            }
+        },
+        "response.FailureResponse": {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "status": {
+                    "type": "string"
+                }
+            }
+        },
+        "response.GeneratePreviewResponse": {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "qr_code": {
+                    "type": "string"
+                },
+                "status": {
+                    "type": "string"
+                }
+            }
+        }
+    }
+}
\ No newline at end of file
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
new file mode 100644
index 0000000..1699cfd
--- /dev/null
+++ b/docs/swagger.yaml
@@ -0,0 +1,321 @@
+basePath: /api/v1
+definitions:
+  entity.Meta:
+    properties:
+      meta_collection:
+        items:
+          $ref: '#/definitions/entity.MetaValues'
+        type: array
+    type: object
+  entity.MetaValues:
+    properties:
+      name:
+        type: string
+      values:
+        items:
+          type: string
+        type: array
+    type: object
+  entity.Shorty:
+    properties:
+      TTL:
+        type: string
+      accesses:
+        items:
+          $ref: '#/definitions/entity.ShortyAccess'
+        type: array
+      created_at:
+        type: string
+      deleted_at:
+        type: string
+      id:
+        type: string
+      link:
+        type: string
+      qr_code:
+        type: string
+      redirection_limit:
+        type: integer
+      redirects:
+        type: integer
+      short_link:
+        type: string
+      visits:
+        type: integer
+    type: object
+  entity.ShortyAccess:
+    properties:
+      browser:
+        type: string
+      created_at:
+        type: string
+      extra:
+        type: string
+      id:
+        type: string
+      ip:
+        type: string
+      meta:
+        $ref: '#/definitions/entity.Meta'
+      os:
+        type: string
+      status:
+        type: string
+      user_agent:
+        type: string
+    type: object
+  request.CreateShorty:
+    properties:
+      TTL:
+        type: string
+      link:
+        type: string
+      qr_code:
+        $ref: '#/definitions/request.QRCode'
+      redirection_limit:
+        type: integer
+    type: object
+  request.GeneratePreview:
+    properties:
+      link:
+        type: string
+      qr_code:
+        $ref: '#/definitions/request.QRCode'
+    type: object
+  request.QRCode:
+    properties:
+      background_color:
+        type: string
+      border_width:
+        type: integer
+      create:
+        type: boolean
+      foreground_color:
+        type: string
+      logo:
+        type: string
+      shape:
+        type: string
+      width:
+        type: integer
+    type: object
+  request.UpdateShorty:
+    properties:
+      TTL:
+        type: string
+      cancel:
+        type: boolean
+      link:
+        type: string
+      redirection_limit:
+        type: integer
+    type: object
+  response.FailureResponse:
+    properties:
+      message:
+        items:
+          type: string
+        type: array
+      status:
+        type: string
+    type: object
+  response.GeneratePreviewResponse:
+    properties:
+      message:
+        items:
+          type: string
+        type: array
+      qr_code:
+        type: string
+      status:
+        type: string
+    type: object
+info:
+  contact: {}
+  description: Create your shortlinks with QRCodes and more!
+  title: Pun Sho API
+  version: "0.2"
+paths:
+  /preview:
+    post:
+      description: Creates a QR Code preview for a given url
+      parameters:
+      - description: Authorization token
+        in: header
+        name: token
+        type: string
+      - description: Request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/request.GeneratePreview'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: response
+          schema:
+            $ref: '#/definitions/response.GeneratePreviewResponse'
+        "400":
+          description: error
+          schema:
+            $ref: '#/definitions/response.FailureResponse'
+      summary: Creates a QR Code preview for a given url
+      tags:
+      - Preview
+  /short:
+    get:
+      description: Lists all the shortlinks available
+      parameters:
+      - description: Authorization token
+        in: header
+        name: token
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: response
+          schema:
+            items:
+              $ref: '#/definitions/entity.Shorty'
+            type: array
+        "400":
+          description: error
+          schema:
+            $ref: '#/definitions/response.FailureResponse'
+      summary: Lists your shorlinks
+      tags:
+      - Short
+    post:
+      description: Creates a shortlink for a given url, optionally setting a ttl and
+        a redirection limit
+      parameters:
+      - description: Authorization token
+        in: header
+        name: token
+        type: string
+      - description: Request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/request.CreateShorty'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: response
+          schema:
+            $ref: '#/definitions/entity.Shorty'
+        "400":
+          description: error
+          schema:
+            $ref: '#/definitions/response.FailureResponse'
+      summary: Creates a shortlink for a given url
+      tags:
+      - Short
+  /short/{id}:
+    delete:
+      description: Deletes a shortlink
+      parameters:
+      - description: Authorization token
+        in: header
+        name: token
+        type: string
+      - description: ShortLink ID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/request.UpdateShorty'
+      produces:
+      - application/json
+      responses:
+        "204":
+          description: No Content
+          schema:
+            type: string
+        "400":
+          description: error
+          schema:
+            $ref: '#/definitions/response.FailureResponse'
+        "404":
+          description: not found
+          schema:
+            $ref: '#/definitions/response.FailureResponse'
+      summary: Deletes a shortlink
+      tags:
+      - Short
+    get:
+      description: retrieves full information for the give shortlink
+      parameters:
+      - description: Authorization token
+        in: header
+        name: token
+        type: string
+      - description: ShortLink ID
+        in: path
+        name: id
+        required: true
+        type: string
+      responses:
+        "200":
+          description: response
+          schema:
+            $ref: '#/definitions/entity.Shorty'
+        "400":
+          description: error
+          schema:
+            $ref: '#/definitions/response.FailureResponse'
+        "404":
+          description: not found
+          schema:
+            $ref: '#/definitions/response.FailureResponse'
+      summary: get your shortlink information
+      tags:
+      - Short
+    patch:
+      description: Edits a shortlink, allowing to set TTL, cancel the link or change
+        the redirection limit or associated link
+      parameters:
+      - description: Authorization token
+        in: header
+        name: token
+        type: string
+      - description: ShortLink ID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/request.UpdateShorty'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: response
+          schema:
+            $ref: '#/definitions/entity.Shorty'
+        "400":
+          description: error
+          schema:
+            $ref: '#/definitions/response.FailureResponse'
+        "404":
+          description: not found
+          schema:
+            $ref: '#/definitions/response.FailureResponse'
+      summary: Edits a shortlink
+      tags:
+      - Short
+swagger: "2.0"
diff --git a/main.go b/main.go
index 448bba0..9540ff7 100644
--- a/main.go
+++ b/main.go
@@ -17,6 +17,12 @@ import (
 
 const Timestamp = "timestamp"
 
+// @title           Pun Sho API
+// @version         0.2
+// @description     Create your shortlinks with QRCodes and more!
+
+// @BasePath  /api/v1
+
 func main() {
 	loggerConfig := zap.NewProductionConfig()
 	loggerConfig.EncoderConfig.TimeKey = Timestamp