diff --git a/composer.json b/composer.json index 58e9d40d..13947ddf 100644 --- a/composer.json +++ b/composer.json @@ -42,7 +42,8 @@ "roave/security-advisories": "dev-master", "filp/whoops": "^2.0", "symfony/var-dumper": "^3.0", - "vlucas/phpdotenv": "^2.2" + "vlucas/phpdotenv": "^2.2", + "phly/changelog-generator": "^2.1" }, "autoload": { "psr-4": { diff --git a/docs/swagger.json b/docs/swagger.json new file mode 100644 index 00000000..d1a5ef97 --- /dev/null +++ b/docs/swagger.json @@ -0,0 +1,416 @@ +{ + "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" + }, + { + "$ref": "#/parameters/Authorization" + } + ], + "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" + } + }, + { + "$ref": "#/parameters/Authorization" + } + ], + "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 + }, + { + "$ref": "#/parameters/Authorization" + } + ], + "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." + } + } + } + }, + "400": { + "description": "Provided shortCode does not match the character set currently used by the app to generate short codes.", + "schema": { + "$ref": "#/definitions/Error" + } + }, + "404": { + "description": "No URL was found for provided short code.", + "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 + }, + { + "$ref": "#/parameters/Authorization" + } + ], + "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 + }, + { + "$ref": "#/parameters/Authorization" + } + ], + "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." + } + } + } + }, + + "parameters": { + "Authorization": { + "name": "Authorization", + "in": "header", + "description": "The authorization token with Bearer type", + "required": true, + "type": "string" + } + } +} diff --git a/docs/swagger.yaml b/docs/swagger.yaml deleted file mode 100644 index 27037fe5..00000000 --- a/docs/swagger.yaml +++ /dev/null @@ -1,289 +0,0 @@ -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.