Added swagger documentation file

docs/swagger.yaml

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