From 13a3ab00761a7aa56780fd5d066e618da102e8c5 Mon Sep 17 00:00:00 2001
From: mg
Date: Tue, 25 Apr 2023 20:52:45 +0200
Subject: add swagger (#1)

Co-authored-by: Michael Grote <michael.grote@posteo.de>
Reviewed-on: https://git.mgrote.net/mg/python-api-server/pulls/1
---
 app.py | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)

(limited to 'app.py')

diff --git a/app.py b/app.py
index cb1cf9d..dd49463 100644
--- a/app.py
+++ b/app.py
@@ -3,8 +3,10 @@ import re
 import uuid
 from flask import Flask, request, jsonify, send_from_directory
 import datetime
+from flasgger import Swagger, swag_from
 
 app = Flask(__name__)
+swagger = Swagger(app)
 app.config['UPLOAD_DIRECTORY'] = os.environ.get('UPLOAD_DIRECTORY', '/uploads')
 app.config['MAX_CONTENT_LENGTH'] = int(os.environ.get('MAX_CONTENT_LENGTH', '5')) * 1024 * 1024  # in MB
 
@@ -17,10 +19,41 @@ def is_valid_filename(filename):
 
 @app.route('/health', methods=['GET'])
 def health_check():
+    """
+    Endpoint for health check.
+    ---
+    responses:
+        200:
+            description: OK
+    """
     return 'OK'
 
 @app.route('/upload', methods=['POST'])
 def upload_file():
+    """
+    Endpoint for uploading files.
+    Filename can only contain alphanumeric characters, hyphens, underscores, and periods.
+    If the filename is the same as an existing file, this file will be overwritten.
+    ---
+    parameters:
+        - name: file
+          in: formData
+          type: file
+          required: true
+          description: The file to upload.
+        - name: token
+          in: header
+          type: string
+          required: true
+          description: Authentication token.
+    responses:
+        200:
+            description: File uploaded successfully.
+        400:
+            description: Bad request.
+        401:
+            description: Unauthorized.
+    """
     if 'file' not in request.files:
         return jsonify({'error': 'No file part in the request'}), 400
 
@@ -43,6 +76,21 @@ def upload_file():
 
 @app.route('/download/<filename>', methods=['GET'])
 def download_file(filename):
+    """
+    Endpoint for downloading files.
+    ---
+    parameters:
+        - name: filename
+          in: path
+          type: string
+          required: true
+          description: The name of the file to download.
+    responses:
+        200:
+            description: File downloaded successfully.
+        404:
+            description: File not found.
+    """
     try:
         return send_from_directory(app.config['UPLOAD_DIRECTORY'], filename)
     except FileNotFoundError:
@@ -50,6 +98,28 @@ def download_file(filename):
 
 @app.route('/delete/<filename>', methods=['DELETE'])
 def delete_file(filename):
+    """
+    Endpoint for deleting files.
+    ---
+    parameters:
+        - name: filename
+          in: path
+          type: string
+          required: true
+          description: The name of the file to delete.
+        - name: token
+          in: header
+          type: string
+          required: true
+          description: Authentication token.
+    responses:
+        200:
+            description: File deleted successfully.
+        401:
+            description: Unauthorized.
+        404:
+            description: File not found.
+    """
     if 'token' not in request.headers:
         return jsonify({'error': 'No token supplied'}), 401
 
@@ -63,8 +133,26 @@ def delete_file(filename):
     os.remove(file_path)
     return jsonify({'success': 'File \'{}\' successfully deleted'.format(filename)})
 
+
 @app.route('/list', methods=['GET'])
 def list_files():
+    """
+    Endpoint for listing  files.
+    ---
+    parameters:
+        - name: token
+          in: header
+          type: string
+          required: true
+          description: Authentication token.
+    responses:
+        200:
+            description: Listed files successfully.
+        400:
+            description: Bad request.
+        401:
+            description: Unauthorized.
+    """
     if 'token' not in request.headers:
         return jsonify({'error': 'No token supplied'}), 401
 
-- 
cgit v1.2.3