From c898cef2770a3a47285ee9d1012a61d1c650cbe6 Mon Sep 17 00:00:00 2001
From: Alejandro Celaya <alejandro@alejandrocelaya.com>
Date: Sun, 9 Dec 2018 15:18:10 +0100
Subject: [PATCH] Documented first non-rest endpoint

---
 docs/swagger/paths/{shortCode}.json | 36 +++++++++++++++++++++++++++++
 docs/swagger/swagger.json           | 35 +++++++++++++++++++---------
 2 files changed, 60 insertions(+), 11 deletions(-)
 create mode 100644 docs/swagger/paths/{shortCode}.json

diff --git a/docs/swagger/paths/{shortCode}.json b/docs/swagger/paths/{shortCode}.json
new file mode 100644
index 00000000..eccd5ba1
--- /dev/null
+++ b/docs/swagger/paths/{shortCode}.json
@@ -0,0 +1,36 @@
+{
+    "get": {
+        "operationId": "shortUrl",
+        "tags": [
+            "URL Shortener"
+        ],
+        "summary": "Short URL",
+        "description": "Represents a short URL. Tracks the visit and redirects tio the corresponding long URL",
+        "parameters": [
+            {
+                "name": "shortCode",
+                "in": "path",
+                "description": "The short code to resolve.",
+                "required": true,
+                "schema": {
+                    "type": "string"
+                }
+            }
+        ],
+        "responses": {
+            "302": {
+                "description": "Visit properly tracked and redirected"
+            },
+            "500": {
+                "description": "Unexpected error.",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "$ref": "../definitions/Error.json"
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/docs/swagger/swagger.json b/docs/swagger/swagger.json
index 1ca741bb..6300fddf 100644
--- a/docs/swagger/swagger.json
+++ b/docs/swagger/swagger.json
@@ -6,15 +6,20 @@
         "version": "1.0"
     },
 
+    "externalDocs": {
+        "url": "https://shlink.io/api-docs",
+        "description": "Find more info on how to start using this API here"
+    },
+
     "servers": [
         {
-            "url": "{schema}://{server}/rest",
+            "url": "{scheme}://{host}",
             "variables": {
-                "schema": {
+                "scheme": {
                     "default": "https",
                     "enum": ["https", "http"]
                 },
-                "server": {
+                "host": {
                     "default": ""
                 }
             }
@@ -51,35 +56,43 @@
             "name": "Visits",
             "description": "Operations to manage visits on short URLs"
         },
+        {
+            "name": "URL Shortener",
+            "description": "Non-rest endpoints, used to be publicly exposed"
+        },
         {
             "name": "Authentication",
-            "description": "Authentication-related endpoints"
+            "description": "**[Deprecated]** Authentication-related endpoints"
         }
     ],
 
     "paths": {
-        "/v1/short-urls": {
+        "/rest/v1/short-urls": {
             "$ref": "paths/v1_short-urls.json"
         },
-        "/v1/short-urls/shorten": {
+        "/rest/v1/short-urls/shorten": {
             "$ref": "paths/v1_short-urls_shorten.json"
         },
-        "/v1/short-urls/{shortCode}": {
+        "/rest/v1/short-urls/{shortCode}": {
             "$ref": "paths/v1_short-urls_{shortCode}.json"
         },
-        "/v1/short-urls/{shortCode}/tags": {
+        "/rest/v1/short-urls/{shortCode}/tags": {
             "$ref": "paths/v1_short-urls_{shortCode}_tags.json"
         },
 
-        "/v1/tags": {
+        "/rest/v1/tags": {
             "$ref": "paths/v1_tags.json"
         },
 
-        "/v1/short-urls/{shortCode}/visits": {
+        "/rest/v1/short-urls/{shortCode}/visits": {
             "$ref": "paths/v1_short-urls_{shortCode}_visits.json"
         },
 
-        "/v1/authenticate": {
+        "/{shortCode}": {
+            "$ref": "paths/{shortCode}.json"
+        },
+
+        "/rest/v1/authenticate": {
             "$ref": "paths/v1_authenticate.json"
         }
     }