Include REST API endpoints documentation

Author: ikus060

.gitignore

@@ -14,6 +14,8 @@ develop-eggs
 .installed.cfg
 .venv
 .vscode
+doc/_static/openapi.json
+doc/endpoints.md
 
 # Installer logs
 pip-log.txt

doc/api.md

@@ -0,0 +1,59 @@
+# RESTful API
+
+## Overview
+
+Minarca Server provides a RESTful API that allows users to interact with the application programmatically. The API is accessible via the `/api` endpoint, and different endpoints provide access to various functionalities, including retrieving application information, managing user settings, working with access tokens, SSH keys, and repository settings.
+
+## Authentication
+
+The REST API endpoints (`/api`) supports two modes of authentication:
+
+1. **Username and Password:** The same credentials used for authenticating via the web interface.
+2. **Username and Access Token:** Access tokens act as passwords, and their scope may limit access to specific API endpoints. When Multi-Factor Authentication (MFA) is enabled, this mode is supported.
+
+## Input Payloads
+
+The Minarca Server RESTful API supports input payloads in two commonly used formats: `application/json` and `application/x-www-form-urlencoded`. This flexibility allows users to choose the payload format that best suits their needs when interacting with the API.
+
+- **`application/json`**: Use this format for JSON-encoded data. The payload should be a valid JSON object sent in the request body.
+
+- **`application/x-www-form-urlencoded`**: This format is suitable for URL-encoded data, typically used in HTML forms. Key-value pairs are sent in the request body with a `Content-Type` header set to `application/x-www-form-urlencoded`.
+
+Please ensure that the appropriate `Content-Type` header is set in your API requests to match the payload format being used.
+
+## Rate limits
+
+REST API requests are subject to rate limit settings. These settings reduce the risk of Minarca Server instance being overloaded.
+
+Minarca Server returns HTTP status code 429 for 1 hour, if 20 failed authentication requests were received in the same period of time from a single IP address. The same limit also applied to most POST method in the RESTful API.
+
+This limit is configurable trought the `rate-limit` settings.
+
+### Example using cURL
+
+Here's an example of using cURL to make a request to the Minarca Server API with a JSON payload:
+
+```bash
+# Example using application/json payload
+curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"fullname": "John Doe", "email": "[email protected]", "lang": "en", "report_time_range": "30"}' https://example.com/api/currentuser
+```
+
+And for a request with `application/x-www-form-urlencoded` payload:
+
+```bash
+# Example using application/x-www-form-urlencoded payload
+curl -u admin:admin123 -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'fullname=John%20Doe&[email protected]&lang=en&report_time_range=30' https://example.com/api/currentuser
+```
+
+Adjust the payload data and endpoint URL accordingly based on your specific use case.
+
+---
+
+All available endpoints are documented using the OpenAPI (Swagger) specification, accessible from your Minarca Server server at `https://example.com/api/openapi.json`. Access to the URL requires authentication.
+
+```{toctree}
+---
+maxdepth: 3
+---
+endpoints
+```

doc/index-server.rst

@@ -9,3 +9,4 @@ Minarca Server
    configuration
    settings
    hardening
+   api

doc/openapi.json

@@ -0,0 +1,97 @@
+# Copyright (C) 2023 IKUS Software. All rights reserved.
+# IKUS Software inc. PROPRIETARY/CONFIDENTIAL.
+# Use is subject to license terms.
+#
+# This script is used to generate openapi.json file offline.
+#
+# Did not find an alternative to generate markdown or rst from my spec file.
+# Either the solution is obsolete or failing
+# So let use this quick and simple solution.
+import json
+import os
+
+import cherrypy
+from minarca_server.app import MinarcaApplication
+from minarca_server.config import parse_args
+from rdiffweb.controller.api_openapi import OpenAPI
+
+# Change location of cwd for script location.
+os.chdir(os.path.dirname(os.path.abspath(__file__)))
+
+# Generate spec file.
+cfg = parse_args(
+    args=['--database-uri', 'sqlite://', '--minarca-user-dir-owner', 'nobody', '--minarca-user-dir-group', 'nogroup']
+)
+app = cherrypy.request.app = MinarcaApplication(cfg)
+api_spec = OpenAPI()._generate_spec(app.root)
+with open("_static/openapi.json", 'w') as fp:
+    json.dump(api_spec, fp)
+
+
+def generate_markdown_for_path(path, methods):
+    md_content = []
+    for method, details in methods.items():
+        md_content.append(f"\n### {method.upper()} {path}")
+
+        if "description" in details:
+            md_content.append(f"**Description:**\n{details['description']}\n")
+
+        # Parameters
+        parameters = details.get("parameters", [])
+        if parameters:
+            md_content.append("**Parameters:**")
+            for param in parameters:
+                param_name = param.get('name', 'Unnamed')
+                param_in = param.get('in', 'unknown')
+                param_required = " Required" if param.get('required', False) else ""
+                param_default = f" Default: {param.get('default')}" if "default" in param else ""
+                md_content.append(f"- **{param_name}** (in {param_in}){param_required}{param_default}")
+            md_content.append("")
+
+        # Responses
+        md_content.append("**Responses:**")
+        for status, response in details.get("responses", {}).items():
+            md_content.append(f"- **{status}**: {response.get('description', 'No description')}")
+            content = response.get("content", {})
+            if content:
+                md_content.append("  - **Content:** " + ", ".join(content.keys()))
+
+    return md_content
+
+
+def generate_markdown_from_openapi(openapi_json, output_file):
+    """
+    Generate a Markdown file from an OpenAPI JSON specification.
+
+    :param openapi_json: Path to the OpenAPI JSON file.
+    :param output_file: Path to the output Markdown file.
+    """
+    with open(openapi_json, "r", encoding="utf-8") as f:
+        spec = json.load(f)
+
+    md_content = []
+
+    # Separate API and non-API endpoints
+    md_content.append("# All Endpoints")
+
+    md_content.append("## REST API Endpoints")
+
+    for path in sorted(spec.get("paths", [])):
+        if path.startswith('/api'):
+            md_content.extend(generate_markdown_for_path(path, spec["paths"][path]))
+
+    md_content.append("## Other Endpoints")
+
+    for path in sorted(spec.get("paths", [])):
+        if not path.startswith('/api'):
+            md_content.extend(generate_markdown_for_path(path, spec["paths"][path]))
+
+    # Write to file
+    with open(output_file, "w", encoding="utf-8") as f:
+        f.write("\n".join(md_content))
+
+    print(f"Markdown documentation generated: {output_file}")
+
+
+# Example usage
+generate_markdown_from_openapi("_static/openapi.json", "endpoints.md")

doc/openapi.py

@@ -1 +1 @@
-sonar.exclusions=**/test_*.py,**/doc/conf.py,**/patches/apply.py
+sonar.exclusions=**/test_*.py,**/doc/*.py,**/patches/apply.py

sonar-project.properties

@@ -40,7 +40,12 @@ relative_files = True
 deps =
   sphinx
   myst-parser
-commands = sphinx-build -W -b html -d {envtmpdir}/doctrees doc {envtmpdir}/html
+  # For Swagger API docs
+  minarca-server @ git+https://gitlab.com/ikus-soft/[email protected]
+commands = 
+  # Generate openapi.json
+  python3 doc/openapi.py
+  sphinx-build -W -b html -d {envtmpdir}/doctrees doc {envtmpdir}/html
 
 [testenv:pyinstaller-{linux,mac,win}]
 deps =
@@ -67,18 +72,18 @@ commands =
 
 [testenv:black]
 deps = black==24.3.0
-commands = black --check --diff minarca_client
+commands = black --check --diff minarca_client doc
 skip_install = true
 
 [testenv:flake8]
 deps =
   flake8
-commands = flake8 minarca_client
+commands = flake8 minarca_client doc
 skip_install = true
 
 [testenv:isort]
 deps = isort>=5.0.1
-commands = isort --check --diff minarca_client
+commands = isort --check --diff minarca_client doc
 skip_install = true
 
 [testenv:babel_extract]