mirrors/shlink
1
0
Fork 0
mirror of https://github.com/shlinkio/shlink.git synced 2025-02-16 15:29:54 +03:00
Code Issues Projects Releases Packages Wiki Activity

Updated swagger docs, with new API v3 error types

Browse source
This commit is contained in:
Alejandro Celaya 2022-08-14 13:55:43 +02:00
parent 750a546faf
commit 672b728379
15 changed files with 267 additions and 74 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

0
docs/swagger/examples/short-url-invalid-args.json → docs/swagger/examples/short-url-invalid-args-v2.json
View file

9
docs/swagger/examples/short-url-invalid-args-v3.json Normal file
View file

@ -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"]
}
}

0
docs/swagger/examples/short-url-not-found.json → docs/swagger/examples/short-url-not-found-v2.json
View file

9
docs/swagger/examples/short-url-not-found-v3.json Normal file
View file

@ -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"
}
}

0
docs/swagger/examples/tag-not-found.json → docs/swagger/examples/tag-not-found-v2.json
View file

9
docs/swagger/examples/tag-not-found-v3.json Normal file
View file

@ -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"
}
}

33
docs/swagger/paths/v1_short-urls.json
View file

@ -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",

34
docs/swagger/paths/v1_short-urls_shorten.json
View file

@ -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"
}
}
}
}
},

56
docs/swagger/paths/v1_short-urls_{shortCode}.json
View file

@ -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"
}
}
}

7
docs/swagger/paths/v1_short-urls_{shortCode}_visits.json
View file

@ -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"
}
}
}

104
docs/swagger/paths/v1_tags.json
View file

@ -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
}
}
}
}
}

25
docs/swagger/paths/v2_domains_redirects.json
View file

@ -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"]
}
}
}
}
}

25
docs/swagger/paths/v2_domains_{domain}_visits.json
View file

@ -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"
}
}
}
}
}

22
docs/swagger/paths/v2_mercure-info.json
View file

@ -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
}
}
}
}
}

8
docs/swagger/paths/v2_tags_{tag}_visits.json
View file

@ -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"
}
}
}