Merge pull request #2 from CodeSignal/dev

Updated documentation and storing docs in json files

Author: matheusgalvao1

app/routes/docs.py

@@ -1,116 +1,35 @@
+import os
 from flask import Blueprint, current_app, json, Response
 from config.auth_config import AuthMethod
 
 docs_bp = Blueprint("docs", __name__)
 
+def load_json_file(filename):
+    """Load and parse a JSON file."""
+    try:
+        with open(filename, 'r') as f:
+            return json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
 @docs_bp.route("", methods=["GET"])
 def api_docs():
     """Provide comprehensive API documentation."""
     docs = {}
 
+    # Load route documentation in specific order
+    route_files = ['todos.json', 'notes.json']  # Define order explicitly
+    docs_dir = os.path.join(current_app.root_path, '..', 'docs', 'routes')
+    
+    for filename in route_files:
+        route_docs = load_json_file(os.path.join(docs_dir, filename))
+        docs.update(route_docs)
+    
+    # Load authentication documentation
     auth_docs = _get_auth_docs()
     if auth_docs:
         docs["authentication"] = auth_docs
-        
-    docs.update({
-        "/todos": {
-            "GET": {
-                "description": "Fetch all TODO items with optional filtering and pagination.",
-                "query_params": {
-                    "done": "Filter by completion status (true/false).",
-                    "title": "Filter by TODO item title prefix.",
-                    "page": "Page number for pagination (optional, starts at 1).",
-                    "limit": "Number of items per page (optional)."
-                },
-                "responses": {
-                    "200": "List of todo items"
-                }
-            },
-            "POST": {
-                "description": "Add a new TODO item.",
-                "body_params": {
-                    "title": "The TODO item title (required).",
-                    "done": "Completion status (optional, default: false).",
-                    "description": "Detailed TODO item description (optional)."
-                },
-                "responses": {
-                    "201": "Created todo item",
-                    "400": "Invalid request (missing title)"
-                }
-            }
-        },
-        "/todos/<int:todo_id>": {
-            "GET": {
-                "description": "Fetch a single TODO item by its ID.",
-                "responses": {
-                    "200": "Todo item",
-                    "404": "Todo not found"
-                }
-            },
-            "PUT": {
-                "description": "Replace an existing TODO item by its ID (all fields required).",
-                "body_params": {
-                    "title": "The TODO item title (required).",
-                    "done": "Completion status (required).",
-                    "description": "Detailed TODO item description (required)."
-                },
-                "responses": {
-                    "200": "Updated todo item",
-                    "400": "Invalid request (missing required fields)",
-                    "404": "Todo not found"
-                }
-            },
-            "PATCH": {
-                "description": "Update part of a TODO item by its ID (any field can be provided).",
-                "body_params": {
-                    "title": "The TODO item title (optional).",
-                    "done": "Completion status (optional).",
-                    "description": "Detailed TODO item description (optional)."
-                },
-                "responses": {
-                    "200": "Updated todo item",
-                    "400": "Invalid request (empty body)",
-                    "404": "Todo not found"
-                }
-            },
-            "DELETE": {
-                "description": "Delete a TODO item by its ID.",
-                "responses": {
-                    "204": "Todo deleted successfully",
-                    "404": "Todo not found"
-                }
-            }
-        },
-        "/notes": {
-            "POST": {
-                "description": "Upload a new note file.",
-                "content_type": "multipart/form-data",
-                "form_params": {
-                    "file": "The .txt file to upload (required, max size: 1MB)"
-                },
-                "responses": {
-                    "201": "Note created successfully",
-                    "400": "Invalid request (empty file, wrong format, etc.)"
-                }
-            }
-        },
-        "/notes/<note_name>": {
-            "GET": {
-                "description": "Download a note by its name.",
-                "responses": {
-                    "200": "Note file content",
-                    "404": "Note not found"
-                }
-            },
-            "DELETE": {
-                "description": "Delete a note by its name.",
-                "responses": {
-                    "204": "Note deleted successfully",
-                    "404": "Note not found"
-                }
-            }
-        }
-    })
+    
     return Response(
         json.dumps(docs, sort_keys=False, indent=2) + "\n",
         mimetype='application/json'
@@ -122,60 +41,21 @@ def _get_auth_docs():
     if not auth_config or auth_config.auth_method == AuthMethod.NONE:
         return None
 
-    auth_docs = {
-        AuthMethod.API_KEY: {
-            "method": "api_key",
-            "description": "API Key authentication required for protected endpoints.",
-            "how_to_authenticate": "Include your API key in the X-API-Key header for all requests.",
-            "example": {
-                "headers": {
-                    "X-API-Key": "your-api-key-here"
-                }
-            },
-            "protected_endpoints": ["/todos/*", "/notes/*"]
-        },
-        AuthMethod.JWT: {
-            "method": "jwt",
-            "description": "JWT (JSON Web Token) authentication required for protected endpoints.",
-            "how_to_authenticate": "1. Get a token via /auth/login or /auth/signup\n2. Include the token in the Authorization header.",
-            "endpoints": {
-                "/auth/signup": {
-                    "method": "POST",
-                    "body": {"username": "string", "password": "string"},
-                    "response": {"token": "string"}
-                },
-                "/auth/login": {
-                    "method": "POST",
-                    "body": {"username": "string", "password": "string"},
-                    "response": {"token": "string"}
-                }
-            },
-            "example": {
-                "headers": {
-                    "Authorization": "Bearer your-jwt-token-here"
-                }
-            },
-            "protected_endpoints": ["/todos/*", "/notes/*"]
-        },
-        AuthMethod.SESSION: {
-            "method": "session",
-            "description": "Session-based authentication required for protected endpoints.",
-            "how_to_authenticate": "1. Login via /auth/login or signup via /auth/signup\n2. Session cookie will be automatically managed by your browser.",
-            "endpoints": {
-                "/auth/signup": {
-                    "method": "POST",
-                    "body": {"username": "string", "password": "string"}
-                },
-                "/auth/login": {
-                    "method": "POST",
-                    "body": {"username": "string", "password": "string"}
-                },
-                "/auth/logout": {
-                    "method": "POST"
-                }
-            },
-            "protected_endpoints": ["/todos/*", "/notes/*"]
-        }
+    auth_method_map = {
+        AuthMethod.API_KEY: 'api_key',
+        AuthMethod.JWT: 'jwt',
+        AuthMethod.SESSION: 'session'
     }
 
-    return auth_docs.get(auth_config.auth_method, {"error": "Unknown authentication method"})
+    method_name = auth_method_map.get(auth_config.auth_method)
+    if not method_name:
+        return {"error": "Unknown authentication method"}
+    
+    auth_file = os.path.join(
+        current_app.root_path, 
+        '..', 
+        'docs',
+        'auth',
+        f'{method_name}.json'
+    )
+    return load_json_file(auth_file)

docs/auth/api_key.json

@@ -0,0 +1,11 @@
+{
+  "method": "api_key",
+  "description": "API Key authentication required for protected endpoints.",
+  "how_to_authenticate": "Include your API key in the X-API-Key header for all requests.",
+  "example": {
+    "headers": {
+      "X-API-Key": "your-api-key-here"
+    }
+  },
+  "protected_endpoints": ["/todos/*", "/notes/*"]
+} 

docs/auth/jwt.json

@@ -0,0 +1,41 @@
+{
+  "method": "jwt",
+  "description": "JWT (JSON Web Token) authentication required for protected endpoints.",
+  "how_to_authenticate": "Create account via /auth/signup, get tokens via /auth/login, include the access token in the Authorization header, use /auth/refresh with refresh token to get new tokens, use /auth/logout with both tokens to end session",
+  "endpoints": {
+    "/auth/signup": {
+      "method": "POST",
+      "body": {"username": "string", "password": "string"},
+      "response": {"message": "Signup successful. Please log in to continue."}
+    },
+    "/auth/login": {
+      "method": "POST",
+      "body": {"username": "string", "password": "string"},
+      "response": {
+        "message": "Login successful",
+        "access_token": "string",
+        "refresh_token": "string"
+      }
+    },
+    "/auth/refresh": {
+      "method": "POST",
+      "body": {"refresh_token": "string"},
+      "response": {
+        "access_token": "string",
+        "refresh_token": "string"
+      }
+    },
+    "/auth/logout": {
+      "method": "POST",
+      "headers": {"Authorization": "Bearer <access_token>"},
+      "body": {"refresh_token": "string"},
+      "response": {"message": "string"}
+    }
+  },
+  "example": {
+    "headers": {
+      "Authorization": "Bearer your-jwt-access-token-here"
+    }
+  },
+  "protected_endpoints": ["/todos/*", "/notes/*"]
+} 

docs/auth/session.json

@@ -0,0 +1,22 @@
+{
+  "method": "session",
+  "description": "Session-based authentication required for protected endpoints.",
+  "how_to_authenticate": "Create account via /auth/signup, login via /auth/login to create a session, session cookie will be automatically managed by your client, use /auth/logout to end your session",
+  "endpoints": {
+    "/auth/signup": {
+      "method": "POST",
+      "body": {"username": "string", "password": "string"},
+      "response": {"message": "Signup successful. Please log in to continue."}
+    },
+    "/auth/login": {
+      "method": "POST",
+      "body": {"username": "string", "password": "string"},
+      "response": {"message": "Login successful"}
+    },
+    "/auth/logout": {
+      "method": "POST",
+      "response": {"message": "Logout successful"}
+    }
+  },
+  "protected_endpoints": ["/todos/*", "/notes/*"]
+} 

docs/routes/notes.json

@@ -0,0 +1,31 @@
+{
+  "/notes": {
+    "POST": {
+      "description": "Upload a new note file.",
+      "content_type": "multipart/form-data",
+      "form_params": {
+        "file": "The .txt file to upload (required, max size: 1MB)"
+      },
+      "responses": {
+        "201": "Note created successfully",
+        "400": "Invalid request (empty file, wrong format, etc.)"
+      }
+    }
+  },
+  "/notes/<note_name>": {
+    "GET": {
+      "description": "Download a note by its name.",
+      "responses": {
+        "200": "Note file content",
+        "404": "Note not found"
+      }
+    },
+    "DELETE": {
+      "description": "Delete a note by its name.",
+      "responses": {
+        "204": "Note deleted successfully",
+        "404": "Note not found"
+      }
+    }
+  }
+} 

docs/routes/todos.json

@@ -0,0 +1,70 @@
+{
+  "/todos": {
+    "GET": {
+      "description": "Fetch all TODO items with optional filtering and pagination.",
+      "query_params": {
+        "done": "Filter by completion status (true/false).",
+        "title": "Filter by TODO item title prefix.",
+        "page": "Page number for pagination (optional, starts at 1).",
+        "limit": "Number of items per page (optional)."
+      },
+      "responses": {
+        "200": "List of todo items"
+      }
+    },
+    "POST": {
+      "description": "Add a new TODO item.",
+      "body_params": {
+        "title": "The TODO item title (required).",
+        "done": "Completion status (optional, default: false).",
+        "description": "Detailed TODO item description (optional)."
+      },
+      "responses": {
+        "201": "Created todo item",
+        "400": "Invalid request (missing title)"
+      }
+    }
+  },
+  "/todos/<int:todo_id>": {
+    "GET": {
+      "description": "Fetch a single TODO item by its ID.",
+      "responses": {
+        "200": "Todo item",
+        "404": "Todo not found"
+      }
+    },
+    "PUT": {
+      "description": "Replace an existing TODO item by its ID (all fields required).",
+      "body_params": {
+        "title": "The TODO item title (required).",
+        "done": "Completion status (required).",
+        "description": "Detailed TODO item description (required)."
+      },
+      "responses": {
+        "200": "Updated todo item",
+        "400": "Invalid request (missing required fields)",
+        "404": "Todo not found"
+      }
+    },
+    "PATCH": {
+      "description": "Update part of a TODO item by its ID (any field can be provided).",
+      "body_params": {
+        "title": "The TODO item title (optional).",
+        "done": "Completion status (optional).",
+        "description": "Detailed TODO item description (optional)."
+      },
+      "responses": {
+        "200": "Updated todo item",
+        "400": "Invalid request (empty body)",
+        "404": "Todo not found"
+      }
+    },
+    "DELETE": {
+      "description": "Delete a TODO item by its ID.",
+      "responses": {
+        "204": "Todo deleted successfully",
+        "404": "Todo not found"
+      }
+    }
+  }
+}