Merge pull request #3 from CodeSignal/swagger

Swagger page

Author: matheusgalvao1

app/main.py

@@ -8,6 +8,7 @@
 from utils.config import load_config, load_initial_todos
 from utils.auth import setup_auth_config
 from services.auth_service import init_auth_service
+from flasgger import Swagger
 import secrets
 
 def create_app(auth_config):
@@ -32,7 +33,26 @@ def create_app(auth_config):
     app.config['SECRET_KEY'] = secrets.token_hex(32)  # Generate secure random secret key
     app.config['auth_config'] = auth_config
     app.config['initial_todos'] = load_initial_todos()  # Load initial todos from config file
-
+    
+    # Configure Swagger
+    template = {
+        "swagger": "2.0",
+        "info": {
+            "title": "Todo API",
+            "description": "A RESTful API for managing todos and notes",
+            "version": "1.0.0"
+        }
+    }
+    
+    app.config['SWAGGER'] = {
+        'title': 'Todo API',
+        'uiversion': 3,
+        'specs_route': '/',
+        'url_prefix': '/swagger'
+    }
+    
+    Swagger(app, template=template)
+    
     # Set up authentication
     init_auth_routes(auth_config)
     auth_middleware = AuthMiddleware(auth_config)

app/routes/notes.py

@@ -5,15 +5,73 @@
 
 @notes_bp.route("", methods=["POST"])
 def upload_note():
-    """Upload a new note in .txt format"""
+    """Upload a new note in .txt format
+    ---
+    tags:
+      - notes
+    parameters:
+      - name: file
+        in: formData
+        type: file
+        required: true
+        description: Text file to upload. Must be .txt format, max size 1MB
+    responses:
+      201:
+        description: Note created successfully
+        schema:
+          type: object
+          properties:
+            message:
+              type: string
+              description: Success message
+            note_name:
+              type: string
+              description: Name of the uploaded note
+      400:
+        description: Invalid request - empty file or wrong format
+    """
     return NoteService.upload_note(request)
 
 @notes_bp.route("/<note_name>", methods=["GET"])
 def download_note(note_name):
-    """Download an existing note by its name"""
+    """Download an existing note by its name
+    ---
+    tags:
+      - notes
+    parameters:
+      - name: note_name
+        in: path
+        type: string
+        required: true
+        description: Name of the note to download
+    responses:
+      200:
+        description: Note file content
+        content:
+          text/plain:
+            schema:
+              type: string
+      404:
+        description: Note not found
+    """
     return NoteService.download_note(note_name)
 
 @notes_bp.route("/<note_name>", methods=["DELETE"])
 def delete_note(note_name):
-    """Delete an existing note by its name"""
+    """Delete an existing note by its name
+    ---
+    tags:
+      - notes
+    parameters:
+      - name: note_name
+        in: path
+        type: string
+        required: true
+        description: Name of the note to delete
+    responses:
+      204:
+        description: Note deleted successfully
+      404:
+        description: Note not found
+    """
     return NoteService.delete_note(note_name) 

app/routes/todos.py

@@ -5,24 +5,252 @@
 
 @todos_bp.route("", methods=["GET"])
 def get_all_todos():
+    """Get all todos with optional filtering and pagination
+    ---
+    tags:
+      - todos
+    parameters:
+      - name: done
+        in: query
+        type: boolean
+        required: false
+        description: Filter by completion status
+      - name: title
+        in: query
+        type: string
+        required: false
+        description: Filter by TODO item title prefix
+      - name: page
+        in: query
+        type: integer
+        required: false
+        description: Page number for pagination (starts at 1)
+      - name: limit
+        in: query
+        type: integer
+        required: false
+        description: Number of items per page
+    responses:
+      200:
+        description: List of todo items
+        schema:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: integer
+                description: The todo ID
+              title:
+                type: string
+                description: The todo title
+              done:
+                type: boolean
+                description: Whether the todo is completed
+              description:
+                type: string
+                description: Detailed todo description
+    """
     return TodoService.get_all_todos(request)
 
 @todos_bp.route("<int:todo_id>", methods=["GET"])
 def get_todo(todo_id):
+    """Get a specific todo by ID
+    ---
+    tags:
+      - todos
+    parameters:
+      - name: todo_id
+        in: path
+        type: integer
+        required: true
+        description: ID of the todo to retrieve
+    responses:
+      200:
+        description: Todo details
+        schema:
+          type: object
+          properties:
+            id:
+              type: integer
+              description: The todo ID
+            title:
+              type: string
+              description: The todo title
+            done:
+              type: boolean
+              description: Whether the todo is completed
+            description:
+              type: string
+              description: Detailed todo description
+      404:
+        description: Todo not found
+    """
     return TodoService.get_todo(todo_id)
 
 @todos_bp.route("", methods=["POST"])
 def add_todo():
+    """Add a new TODO item
+    ---
+    tags:
+      - todos
+    parameters:
+      - name: body
+        in: body
+        required: true
+        schema:
+          type: object
+          required:
+            - title
+          properties:
+            title:
+              type: string
+              description: The TODO item title
+            done:
+              type: boolean
+              description: Completion status. Defaults to false if not provided
+            description:
+              type: string
+              description: Detailed TODO item description
+    responses:
+      201:
+        description: Created todo item
+        schema:
+          type: object
+          properties:
+            id:
+              type: integer
+              description: The todo ID
+            title:
+              type: string
+              description: The todo title
+            done:
+              type: boolean
+              description: Whether the todo is completed
+            description:
+              type: string
+              description: Detailed todo description
+      400:
+        description: Invalid request - missing title
+    """
     return TodoService.add_todo(request)
 
 @todos_bp.route("<int:todo_id>", methods=["PUT"])
 def edit_todo(todo_id):
+    """Replace an existing TODO item (all fields required)
+    ---
+    tags:
+      - todos
+    parameters:
+      - name: todo_id
+        in: path
+        type: integer
+        required: true
+        description: ID of the todo to update
+      - name: body
+        in: body
+        required: true
+        schema:
+          type: object
+          required:
+            - title
+            - done
+            - description
+          properties:
+            title:
+              type: string
+              description: The TODO item title
+            done:
+              type: boolean
+              description: Completion status
+            description:
+              type: string
+              description: Detailed TODO item description
+    responses:
+      200:
+        description: Updated todo item
+        schema:
+          type: object
+          properties:
+            id:
+              type: integer
+            title:
+              type: string
+            done:
+              type: boolean
+            description:
+              type: string
+      400:
+        description: Invalid request (missing required fields)
+      404:
+        description: Todo not found
+    """
     return TodoService.edit_todo(todo_id, request)
 
 @todos_bp.route("<int:todo_id>", methods=["PATCH"])
 def patch_todo(todo_id):
+    """Update part of a TODO item (any field optional)
+    ---
+    tags:
+      - todos
+    parameters:
+      - name: todo_id
+        in: path
+        type: integer
+        required: true
+        description: ID of the todo to update
+      - name: body
+        in: body
+        required: true
+        schema:
+          type: object
+          properties:
+            title:
+              type: string
+              description: The TODO item title
+            done:
+              type: boolean
+              description: Completion status
+            description:
+              type: string
+              description: Detailed TODO item description
+    responses:
+      200:
+        description: Updated todo item
+        schema:
+          type: object
+          properties:
+            id:
+              type: integer
+            title:
+              type: string
+            done:
+              type: boolean
+            description:
+              type: string
+      400:
+        description: Invalid request (empty body)
+      404:
+        description: Todo not found
+    """
     return TodoService.patch_todo(todo_id, request)
 
 @todos_bp.route("<int:todo_id>", methods=["DELETE"])
 def delete_todo(todo_id):
+    """Delete a TODO item
+    ---
+    tags:
+      - todos
+    parameters:
+      - name: todo_id
+        in: path
+        type: integer
+        required: true
+        description: ID of the todo to delete
+    responses:
+      204:
+        description: Todo deleted successfully
+      404:
+        description: Todo not found
+    """
     return TodoService.delete_todo(todo_id)

requirements.txt

@@ -1,3 +1,4 @@
 Flask==2.2.5
 PyJWT==2.8.0
-PyYAML==6.0.1
+PyYAML==6.0.1
+flasgger==0.9.7