From 672b7283790d1b80e0673ca210f59f0e6dc42f01 Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Sun, 14 Aug 2022 13:55:43 +0200 Subject: [PATCH] Updated swagger docs, with new API v3 error types --- ...gs.json => short-url-invalid-args-v2.json} | 0 .../examples/short-url-invalid-args-v3.json | 9 ++ ...found.json => short-url-not-found-v2.json} | 0 .../examples/short-url-not-found-v3.json | 9 ++ ...g-not-found.json => tag-not-found-v2.json} | 0 docs/swagger/examples/tag-not-found-v3.json | 9 ++ docs/swagger/paths/v1_short-urls.json | 33 +++++- docs/swagger/paths/v1_short-urls_shorten.json | 34 ++++-- .../paths/v1_short-urls_{shortCode}.json | 56 +++++++--- .../v1_short-urls_{shortCode}_visits.json | 7 +- docs/swagger/paths/v1_tags.json | 104 +++++++++++++----- docs/swagger/paths/v2_domains_redirects.json | 25 ++++- .../paths/v2_domains_{domain}_visits.json | 25 ++++- docs/swagger/paths/v2_mercure-info.json | 22 +++- docs/swagger/paths/v2_tags_{tag}_visits.json | 8 +- 15 files changed, 267 insertions(+), 74 deletions(-) rename docs/swagger/examples/{short-url-invalid-args.json => short-url-invalid-args-v2.json} (100%) create mode 100644 docs/swagger/examples/short-url-invalid-args-v3.json rename docs/swagger/examples/{short-url-not-found.json => short-url-not-found-v2.json} (100%) create mode 100644 docs/swagger/examples/short-url-not-found-v3.json rename docs/swagger/examples/{tag-not-found.json => tag-not-found-v2.json} (100%) create mode 100644 docs/swagger/examples/tag-not-found-v3.json diff --git a/docs/swagger/examples/short-url-invalid-args.json b/docs/swagger/examples/short-url-invalid-args-v2.json similarity index 100% rename from docs/swagger/examples/short-url-invalid-args.json rename to docs/swagger/examples/short-url-invalid-args-v2.json diff --git a/docs/swagger/examples/short-url-invalid-args-v3.json b/docs/swagger/examples/short-url-invalid-args-v3.json new file mode 100644 index 00000000..3e9171c6 --- /dev/null +++ b/docs/swagger/examples/short-url-invalid-args-v3.json @@ -0,0 +1,9 @@ +{ + "value": { + "title": "Invalid data", + "type": "https://shlink.io/api/error/invalid-data", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": ["maxVisits", "validSince"] + } +} diff --git a/docs/swagger/examples/short-url-not-found.json b/docs/swagger/examples/short-url-not-found-v2.json similarity index 100% rename from docs/swagger/examples/short-url-not-found.json rename to docs/swagger/examples/short-url-not-found-v2.json diff --git a/docs/swagger/examples/short-url-not-found-v3.json b/docs/swagger/examples/short-url-not-found-v3.json new file mode 100644 index 00000000..82f3469c --- /dev/null +++ b/docs/swagger/examples/short-url-not-found-v3.json @@ -0,0 +1,9 @@ +{ + "value": { + "detail": "No URL found with short code \"abc123\"", + "title": "Short URL not found", + "type": "https://shlink.io/api/error/short-url-not-found", + "status": 404, + "shortCode": "abc123" + } +} diff --git a/docs/swagger/examples/tag-not-found.json b/docs/swagger/examples/tag-not-found-v2.json similarity index 100% rename from docs/swagger/examples/tag-not-found.json rename to docs/swagger/examples/tag-not-found-v2.json diff --git a/docs/swagger/examples/tag-not-found-v3.json b/docs/swagger/examples/tag-not-found-v3.json new file mode 100644 index 00000000..62beb42c --- /dev/null +++ b/docs/swagger/examples/tag-not-found-v3.json @@ -0,0 +1,9 @@ +{ + "value": { + "detail": "Tag with name \"foo\" could not be found", + "title": "Tag not found", + "type": "https://shlink.io/api/error/tag-not-found", + "status": 404, + "tag": "foo" + } +} diff --git a/docs/swagger/paths/v1_short-urls.json b/docs/swagger/paths/v1_short-urls.json index 6e8bb015..2675ab61 100644 --- a/docs/swagger/paths/v1_short-urls.json +++ b/docs/swagger/paths/v1_short-urls.json @@ -327,11 +327,11 @@ }, "url": { "type": "string", - "description": "A URL that could not be verified, if the error type is INVALID_URL" + "description": "A URL that could not be verified, if the error type is https://shlink.io/api/error/invalid-url" }, "customSlug": { "type": "string", - "description": "Provided custom slug when the error type is INVALID_SLUG" + "description": "Provided custom slug when the error type is https://shlink.io/api/error/non-unique-slug" }, "domain": { "type": "string", @@ -342,10 +342,31 @@ ] }, "examples": { - "Invalid arguments": { - "$ref": "../examples/short-url-invalid-args.json" + "Invalid arguments with API v3 and newer": { + "$ref": "../examples/short-url-invalid-args-v3.json" }, - "Invalid long URL": { + "Invalid long URL with API v3 and newer": { + "value": { + "title": "Invalid URL", + "type": "https://shlink.io/api/error/invalid-url", + "detail": "Provided URL foo is invalid. Try with a different one.", + "status": 400, + "url": "https://invalid-url.com" + } + }, + "Non-unique slug with API v3 and newer": { + "value": { + "title": "Invalid custom slug", + "type": "https://shlink.io/api/error/non-unique-slug", + "detail": "Provided slug \"my-slug\" is already in use.", + "status": 400, + "customSlug": "my-slug" + } + }, + "Invalid arguments previous to API v3": { + "$ref": "../examples/short-url-invalid-args-v2.json" + }, + "Invalid long URL previous to API v3": { "value": { "title": "Invalid URL", "type": "INVALID_URL", @@ -354,7 +375,7 @@ "url": "https://invalid-url.com" } }, - "Non-unique slug": { + "Non-unique slug previous to API v3": { "value": { "title": "Invalid custom slug", "type": "INVALID_SLUG", diff --git a/docs/swagger/paths/v1_short-urls_shorten.json b/docs/swagger/paths/v1_short-urls_shorten.json index 722476bb..aa26fa1b 100644 --- a/docs/swagger/paths/v1_short-urls_shorten.json +++ b/docs/swagger/paths/v1_short-urls_shorten.json @@ -85,19 +85,39 @@ "schema": { "$ref": "../definitions/Error.json" }, - "example": { - "title": "Invalid URL", - "type": "INVALID_URL", - "detail": "Provided URL foo is invalid. Try with a different one.", - "status": 400, - "url": "https://invalid-url.com" + "examples": { + "API v3 and newer": { + "value": { + "title": "Invalid URL", + "type": "https://shlink.io/api/error/invalid-url", + "detail": "Provided URL foo is invalid. Try with a different one.", + "status": 400, + "url": "https://invalid-url.com" + } + }, + "Previous to API v3": { + "value": { + "title": "Invalid URL", + "type": "INVALID_URL", + "detail": "Provided URL foo is invalid. Try with a different one.", + "status": 400, + "url": "https://invalid-url.com" + } + } } }, "text/plain": { "schema": { "type": "string" }, - "example": "INVALID_URL" + "examples": { + "API v3 and newer": { + "value": "https://shlink.io/api/error/invalid-url" + }, + "Previous to API v3": { + "value": "INVALID_URL" + } + } } } }, diff --git a/docs/swagger/paths/v1_short-urls_{shortCode}.json b/docs/swagger/paths/v1_short-urls_{shortCode}.json index 9065ff89..1b001cc9 100644 --- a/docs/swagger/paths/v1_short-urls_{shortCode}.json +++ b/docs/swagger/paths/v1_short-urls_{shortCode}.json @@ -83,8 +83,11 @@ ] }, "examples": { - "Not found": { - "$ref": "../examples/short-url-not-found.json" + "API v3 and newer": { + "$ref": "../examples/short-url-not-found-v3.json" + }, + "Previous to API v3": { + "$ref": "../examples/short-url-not-found-v2.json" } } } @@ -203,8 +206,11 @@ ] }, "examples": { - "Invalid arguments": { - "$ref": "../examples/short-url-invalid-args.json" + "API v3 and newer": { + "$ref": "../examples/short-url-invalid-args-v3.json" + }, + "Previous to API v3": { + "$ref": "../examples/short-url-invalid-args-v2.json" } } } @@ -236,8 +242,11 @@ ] }, "examples": { - "Not found": { - "$ref": "../examples/short-url-not-found.json" + "API v3 and newer": { + "$ref": "../examples/short-url-not-found-v3.json" + }, + "Previous to API v3": { + "$ref": "../examples/short-url-not-found-v2.json" } } } @@ -318,13 +327,27 @@ } ] }, - "example": { - "title": "Cannot delete short URL", - "type": "INVALID_SHORT_URL_DELETION", - "detail": "Impossible to delete short URL with short code \"abc123\", since it has more than \"15\" visits.", - "status": 422, - "shortCode": "abc123", - "threshold": 15 + "examples": { + "API v3 and newer": { + "value": { + "title": "Cannot delete short URL", + "type": "https://shlink.io/api/error/invalid-short-url-deletion", + "detail": "Impossible to delete short URL with short code \"abc123\", since it has more than \"15\" visits.", + "status": 422, + "shortCode": "abc123", + "threshold": 15 + } + }, + "Previous to API v3": { + "value": { + "title": "Cannot delete short URL", + "type": "INVALID_SHORT_URL_DELETION", + "detail": "Impossible to delete short URL with short code \"abc123\", since it has more than \"15\" visits.", + "status": 422, + "shortCode": "abc123", + "threshold": 15 + } + } } } } @@ -355,8 +378,11 @@ ] }, "examples": { - "Not found": { - "$ref": "../examples/short-url-not-found.json" + "API v3 and newer": { + "$ref": "../examples/short-url-not-found-v3.json" + }, + "Previous to API v3": { + "$ref": "../examples/short-url-not-found-v2.json" } } } diff --git a/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json b/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json index 08a93b68..e86bb698 100644 --- a/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json +++ b/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json @@ -151,8 +151,11 @@ "$ref": "../definitions/Error.json" }, "examples": { - "Short URL not found": { - "$ref": "../examples/short-url-not-found.json" + "Short URL not found with API v3 and newer": { + "$ref": "../examples/short-url-not-found-v3.json" + }, + "Short URL not found previous to API v3": { + "$ref": "../examples/short-url-not-found-v2.json" } } } diff --git a/docs/swagger/paths/v1_tags.json b/docs/swagger/paths/v1_tags.json index a8219bf1..0e77cf3c 100644 --- a/docs/swagger/paths/v1_tags.json +++ b/docs/swagger/paths/v1_tags.json @@ -188,12 +188,25 @@ "schema": { "$ref": "../definitions/Error.json" }, - "example": { - "title": "Invalid data", - "type": "INVALID_ARGUMENT", - "detail": "Provided data is not valid", - "status": 400, - "invalidElements": ["oldName", "newName"] + "examples": { + "API v3 and newer": { + "value": { + "title": "Invalid data", + "type": "https://shlink.io/api/error/invalid-data", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": ["oldName", "newName"] + } + }, + "Previous to API v3": { + "value": { + "title": "Invalid data", + "type": "INVALID_ARGUMENT", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": ["oldName", "newName"] + } + } } } } @@ -205,11 +218,23 @@ "schema": { "$ref": "../definitions/Error.json" }, - "example": { - "detail": "You are not allowed to rename tags", - "title": "Forbidden tag operation", - "type": "FORBIDDEN_OPERATION", - "status": 403 + "examples": { + "API v3 and newer": { + "value": { + "detail": "You are not allowed to rename tags", + "title": "Forbidden tag operation", + "type": "https://shlink.io/api/error/forbidden-tag-operation", + "status": 403 + } + }, + "Previous to API v3": { + "value": { + "detail": "You are not allowed to rename tags", + "title": "Forbidden tag operation", + "type": "FORBIDDEN_OPERATION", + "status": 403 + } + } } } } @@ -222,8 +247,11 @@ "$ref": "../definitions/Error.json" }, "examples": { - "Tag not found": { - "$ref": "../examples/tag-not-found.json" + "API v3 and newer": { + "$ref": "../examples/tag-not-found-v3.json" + }, + "Previous to API v3": { + "$ref": "../examples/tag-not-found-v2.json" } } } @@ -236,13 +264,27 @@ "schema": { "$ref": "../definitions/Error.json" }, - "example": { - "detail": "You cannot rename tag foo, because it already exists", - "title": "Tag conflict", - "type": "TAG_CONFLICT", - "status": 409, - "oldName": "bar", - "newName": "foo" + "examples": { + "API v3 and newer": { + "value": { + "detail": "You cannot rename tag foo, because it already exists", + "title": "Tag conflict", + "type": "https://shlink.io/api/error/tag-conflict", + "status": 409, + "oldName": "bar", + "newName": "foo" + } + }, + "Previous to API v3": { + "value": { + "detail": "You cannot rename tag foo, because it already exists", + "title": "Tag conflict", + "type": "TAG_CONFLICT", + "status": 409, + "oldName": "bar", + "newName": "foo" + } + } } } } @@ -300,11 +342,23 @@ "schema": { "$ref": "../definitions/Error.json" }, - "example": { - "detail": "You are not allowed to delete tags", - "title": "Forbidden tag operation", - "type": "FORBIDDEN_OPERATION", - "status": 403 + "examples": { + "API v3 and newer": { + "value": { + "detail": "You are not allowed to delete tags", + "title": "Forbidden tag operation", + "type": "https://shlink.io/api/error/forbidden-tag-operation", + "status": 403 + } + }, + "Previous to API v3": { + "value": { + "detail": "You are not allowed to delete tags", + "title": "Forbidden tag operation", + "type": "FORBIDDEN_OPERATION", + "status": 403 + } + } } } } diff --git a/docs/swagger/paths/v2_domains_redirects.json b/docs/swagger/paths/v2_domains_redirects.json index d4d4338c..cc328040 100644 --- a/docs/swagger/paths/v2_domains_redirects.json +++ b/docs/swagger/paths/v2_domains_redirects.json @@ -94,12 +94,25 @@ } ] }, - "example": { - "title": "Invalid data", - "type": "INVALID_ARGUMENT", - "detail": "Provided data is not valid", - "status": 400, - "invalidElements": ["domain", "invalidShortUrlRedirect"] + "examples": { + "API v3 and newer": { + "value": { + "title": "Invalid data", + "type": "https://shlink.io/api/error/invalid-data", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": ["domain", "invalidShortUrlRedirect"] + } + }, + "Previous to API v3": { + "value": { + "title": "Invalid data", + "type": "INVALID_ARGUMENT", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": ["domain", "invalidShortUrlRedirect"] + } + } } } } diff --git a/docs/swagger/paths/v2_domains_{domain}_visits.json b/docs/swagger/paths/v2_domains_{domain}_visits.json index 33389f32..d3acf60e 100644 --- a/docs/swagger/paths/v2_domains_{domain}_visits.json +++ b/docs/swagger/paths/v2_domains_{domain}_visits.json @@ -147,12 +147,25 @@ "schema": { "$ref": "../definitions/Error.json" }, - "example": { - "detail": "Domain with authority \"example.com\" could not be found", - "title": "Domain not found", - "type": "DOMAIN_NOT_FOUND", - "status": 404, - "authority": "example.com" + "examples": { + "API v3 and newer": { + "value": { + "detail": "Domain with authority \"example.com\" could not be found", + "title": "Domain not found", + "type": "https://shlink.io/api/error/domain-not-found", + "status": 404, + "authority": "example.com" + } + }, + "Previous to API v3": { + "value": { + "detail": "Domain with authority \"example.com\" could not be found", + "title": "Domain not found", + "type": "DOMAIN_NOT_FOUND", + "status": 404, + "authority": "example.com" + } + } } } } diff --git a/docs/swagger/paths/v2_mercure-info.json b/docs/swagger/paths/v2_mercure-info.json index a341573f..e637ca33 100644 --- a/docs/swagger/paths/v2_mercure-info.json +++ b/docs/swagger/paths/v2_mercure-info.json @@ -39,11 +39,23 @@ "schema": { "$ref": "../definitions/Error.json" }, - "example": { - "title": "Mercure integration not configured", - "type": "MERCURE_NOT_CONFIGURED", - "detail": "This Shlink instance is not integrated with a mercure hub.", - "status": 501 + "examples": { + "API v3 and newer": { + "value": { + "title": "Mercure integration not configured", + "type": "https://shlink.io/api/error/mercure-not-configured", + "detail": "This Shlink instance is not integrated with a mercure hub.", + "status": 501 + } + }, + "Previous to API v3": { + "value": { + "title": "Mercure integration not configured", + "type": "MERCURE_NOT_CONFIGURED", + "detail": "This Shlink instance is not integrated with a mercure hub.", + "status": 501 + } + } } } } diff --git a/docs/swagger/paths/v2_tags_{tag}_visits.json b/docs/swagger/paths/v2_tags_{tag}_visits.json index 109cb1d0..d40b7020 100644 --- a/docs/swagger/paths/v2_tags_{tag}_visits.json +++ b/docs/swagger/paths/v2_tags_{tag}_visits.json @@ -148,8 +148,12 @@ "$ref": "../definitions/Error.json" }, "examples": { - "Tag not found": { - "$ref": "../examples/tag-not-found.json" + + "API v3 and newer": { + "$ref": "../examples/tag-not-found-v3.json" + }, + "Previous to API v3": { + "$ref": "../examples/tag-not-found-v2.json" } } }