mirror of
https://github.com/shlinkio/shlink.git
synced 2024-11-26 23:18:37 +03:00
Added swagger documentation file
This commit is contained in:
Alejandro Celaya
parent
fe4a4aef34
commit
924ba58f73
1 changed files with 289 additions and 0 deletions
289
docs/swagger.yaml
Normal file
289
docs/swagger.yaml
Normal file
|
|
@ -0,0 +1,289 @@
|
|||
swagger: '2.0'
|
||||
info:
|
||||
title: Shlink
|
||||
description: Shlink, the self-hosted URL shortener
|
||||
version: "1.2.0"
|
||||
|
||||
schemes:
|
||||
- https
|
||||
|
||||
basePath: /rest
|
||||
produces:
|
||||
- application/json
|
||||
|
||||
paths:
|
||||
/authenticate:
|
||||
post:
|
||||
description: Performs an authentication
|
||||
parameters:
|
||||
- name: apiKey
|
||||
in: formData
|
||||
description: The API key to authenticate with
|
||||
required: true
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: The authentication worked.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
description: The authentication token that needs to be sent in the Authorization header
|
||||
400:
|
||||
description: An API key was not provided.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
401:
|
||||
description: The API key is incorrect, is disabled or has expired.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
500:
|
||||
description: Unexpected error.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
/short-codes:
|
||||
get:
|
||||
description: Returns the list of short codes
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
description: The page to be displayed. Defaults to 1
|
||||
required: false
|
||||
type: integer
|
||||
- name: Authorization
|
||||
in: header
|
||||
description: The authorization token with Bearer type
|
||||
required: true
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: The list of short URLs
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
shortUrls:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/definitions/ShortUrl'
|
||||
pagination:
|
||||
$ref: '#/definitions/Pagination'
|
||||
500:
|
||||
description: Unexpected error.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
post:
|
||||
description: Creates a new short code
|
||||
parameters:
|
||||
- name: longUrl
|
||||
in: formData
|
||||
description: The URL to parse
|
||||
required: true
|
||||
type: string
|
||||
- name: tags
|
||||
in: formData
|
||||
description: The URL to parse
|
||||
required: false
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
- name: Authorization
|
||||
in: header
|
||||
description: The authorization token with Bearer type
|
||||
required: true
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: The result of parsing the long URL
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
longUrl:
|
||||
type: string
|
||||
description: The original long URL that has been parsed
|
||||
shortUrl:
|
||||
type: string
|
||||
description: The generated short URL
|
||||
shortCode:
|
||||
type: string
|
||||
description: the short code that is being used in the short URL
|
||||
400:
|
||||
description: The long URL was not provided or is invalid.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
500:
|
||||
description: Unexpected error.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
/short-codes/{shortCode}:
|
||||
get:
|
||||
description: Get the long URL behind a short code.
|
||||
parameters:
|
||||
- name: shortCode
|
||||
in: path
|
||||
type: string
|
||||
description: The short code to resolve.
|
||||
required: true
|
||||
- name: Authorization
|
||||
in: header
|
||||
description: The authorization token with Bearer type
|
||||
required: true
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: The long URL behind a short code.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
longUrl:
|
||||
type: string
|
||||
description: The original long URL behind the short code.
|
||||
404:
|
||||
description: No URL was found for provided short code.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
400:
|
||||
description: Provided shortCode does not match the character set currently used by the app to generate short codes.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
500:
|
||||
description: Unexpected error.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
/short-codes/{shortCode}/visits:
|
||||
get:
|
||||
description: Get the list of visits on provided short code.
|
||||
parameters:
|
||||
- name: shortCode
|
||||
in: path
|
||||
type: string
|
||||
description: The shortCode from which we want to get the visits.
|
||||
required: true
|
||||
- name: Authorization
|
||||
in: header
|
||||
description: The authorization token with Bearer type
|
||||
required: true
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: List of visits.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
visits:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/definitions/Visit'
|
||||
404:
|
||||
description: The short code does not belong to any short URL.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
500:
|
||||
description: Unexpected error.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
/short-codes/{shortCode}/tags:
|
||||
put:
|
||||
description: Edit the tags on provided short code.
|
||||
parameters:
|
||||
- name: shortCode
|
||||
in: path
|
||||
type: string
|
||||
description: The shortCode in which we want to edit tags.
|
||||
required: true
|
||||
- name: tags
|
||||
in: formData
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: The list of tags to set to the short URL.
|
||||
required: true
|
||||
- name: Authorization
|
||||
in: header
|
||||
description: The authorization token with Bearer type
|
||||
required: true
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: List of tags.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
tags:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
400:
|
||||
description: The request body does not contain a "tags" param with array type.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
404:
|
||||
description: No short URL was found for provided short code.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
500:
|
||||
description: Unexpected error.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
|
||||
definitions:
|
||||
ShortUrl:
|
||||
type: object
|
||||
properties:
|
||||
shortCode:
|
||||
type: string
|
||||
description: The short code for this short URL.
|
||||
originalUrl:
|
||||
type: string
|
||||
description: The original long URL.
|
||||
dateCreated:
|
||||
type: string
|
||||
format: date-time
|
||||
description: The date in which the short URL was created in ISO format.
|
||||
visitsCount:
|
||||
type: integer
|
||||
description: The number of visits that this short URL has recieved.
|
||||
tags:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: A list of tags applied to this short URL
|
||||
|
||||
Visit:
|
||||
type: object
|
||||
properties:
|
||||
referer:
|
||||
type: string
|
||||
date:
|
||||
type: string
|
||||
format: date-time
|
||||
remoteAddr:
|
||||
type: string
|
||||
userAgent:
|
||||
type: string
|
||||
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
description: A machine unique code
|
||||
message:
|
||||
type: string
|
||||
description: A human-friendly error message
|
||||
|
||||
Pagination:
|
||||
type: object
|
||||
properties:
|
||||
currentPage:
|
||||
type: integer
|
||||
description: The number of current page being displayed.
|
||||
pagesCount:
|
||||
type: integer
|
||||
description: The total number of pages that can be displayed.
|
||||
Loading…
Reference in a new issue