From c898cef2770a3a47285ee9d1012a61d1c650cbe6 Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Sun, 9 Dec 2018 15:18:10 +0100 Subject: [PATCH 1/3] 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" } } From 6396e7f964aa3bbcd64ae524823be412e7aaf086 Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Sun, 9 Dec 2018 15:43:56 +0100 Subject: [PATCH 2/3] Added other of non-rest endpoints --- docs/swagger/paths/{shortCode}_preview.json | 44 ++++++++++++++++ docs/swagger/paths/{shortCode}_qr-code.json | 56 +++++++++++++++++++++ docs/swagger/paths/{shortCode}_track.json | 44 ++++++++++++++++ docs/swagger/swagger.json | 9 ++++ 4 files changed, 153 insertions(+) create mode 100644 docs/swagger/paths/{shortCode}_preview.json create mode 100644 docs/swagger/paths/{shortCode}_qr-code.json create mode 100644 docs/swagger/paths/{shortCode}_track.json diff --git a/docs/swagger/paths/{shortCode}_preview.json b/docs/swagger/paths/{shortCode}_preview.json new file mode 100644 index 00000000..a35dcf62 --- /dev/null +++ b/docs/swagger/paths/{shortCode}_preview.json @@ -0,0 +1,44 @@ +{ + "get": { + "operationId": "shortUrlPreview", + "tags": [ + "URL Shortener" + ], + "summary": "Short URL preview image", + "description": "Returns the preview of the page behind a short URL", + "parameters": [ + { + "name": "shortCode", + "in": "path", + "description": "The short code to resolve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Image in PNG format", + "content": { + "image/png": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "500": { + "description": "Unexpected error.", + "content": { + "application/json": { + "schema": { + "$ref": "../definitions/Error.json" + } + } + } + } + } + } +} diff --git a/docs/swagger/paths/{shortCode}_qr-code.json b/docs/swagger/paths/{shortCode}_qr-code.json new file mode 100644 index 00000000..14a8fddc --- /dev/null +++ b/docs/swagger/paths/{shortCode}_qr-code.json @@ -0,0 +1,56 @@ +{ + "get": { + "operationId": "shortUrlQrCode", + "tags": [ + "URL Shortener" + ], + "summary": "Short URL QR code", + "description": "Generates a QR code image pointing to a short URL", + "parameters": [ + { + "name": "shortCode", + "in": "path", + "description": "The short code to resolve.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "size", + "in": "path", + "description": "The size of the image to be returned.", + "required": false, + "schema": { + "type": "integer", + "minimum": 50, + "maximum": 1000, + "default": 300 + } + } + ], + "responses": { + "200": { + "description": "QR code in PNG format", + "content": { + "image/png": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "500": { + "description": "Unexpected error.", + "content": { + "application/json": { + "schema": { + "$ref": "../definitions/Error.json" + } + } + } + } + } + } +} diff --git a/docs/swagger/paths/{shortCode}_track.json b/docs/swagger/paths/{shortCode}_track.json new file mode 100644 index 00000000..b4b62bba --- /dev/null +++ b/docs/swagger/paths/{shortCode}_track.json @@ -0,0 +1,44 @@ +{ + "get": { + "operationId": "trackShortUrl", + "tags": [ + "URL Shortener" + ], + "summary": "Short URL tracking pixel", + "description": "Generates a 1px transparent image which can be used to track emails with a short URL", + "parameters": [ + { + "name": "shortCode", + "in": "path", + "description": "The short code to resolve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Image in GIF format", + "content": { + "image/gif": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "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 6300fddf..0ba8231d 100644 --- a/docs/swagger/swagger.json +++ b/docs/swagger/swagger.json @@ -91,6 +91,15 @@ "/{shortCode}": { "$ref": "paths/{shortCode}.json" }, + "/{shortCode}/track": { + "$ref": "paths/{shortCode}_track.json" + }, + "/{shortCode}/qr-code": { + "$ref": "paths/{shortCode}_qr-code.json" + }, + "/{shortCode}/preview": { + "$ref": "paths/{shortCode}_preview.json" + }, "/rest/v1/authenticate": { "$ref": "paths/v1_authenticate.json" From a32bab9fd0bd198bfc8d795f9b620638c502c457 Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Sun, 9 Dec 2018 16:25:24 +0100 Subject: [PATCH 3/3] Updated changelog --- .gitignore | 2 +- CHANGELOG.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index bf3d5ae0..ce581c01 100644 --- a/.gitignore +++ b/.gitignore @@ -6,5 +6,5 @@ vendor/ .env data/database.sqlite data/GeoLite2-City.mmdb -docs/swagger-ui +docs/swagger-ui* docker-compose.override.yml diff --git a/CHANGELOG.md b/CHANGELOG.md index a60dd299..32955747 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), #### Added -* *Nothing* +* [#162](https://github.com/shlinkio/shlink/issues/162) Added non-rest endpoints to swagger definition. #### Changed