Merge pull request #15 from d3-steichman/d3/dev/steichman/selfdoc

API Documentation Generation

Author: Ge0rg3

README.md

@@ -80,7 +80,8 @@ All parameters can have default values, and automatic validation.
 * blacklist: str, A string containing forbidden characters for the value
 * pattern: str, A regex pattern to test for string matches
 * func: Callable -> Union[bool, tuple[bool, str]], A function containing a fully customized logic to validate the value
-* datetime_format: str, str: datetime format string ([datetime format codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes))
+* datetime_format: str: datetime format string ([datetime format codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes))
+* comment: str: A string to display as the argument description in generated documentation (if used)
 
 `File` has the following options:
 * content_types: array of strings, an array of allowed content types.
@@ -107,4 +108,111 @@ def error_handler(err):
 
 @ValidateParameters(error_handler)
 def api(...)
-```
+```
+
+### API Documentation
+Using the data provided through parameters, docstrings, and Flask route registrations, Flask Parameter Validation can generate an API Documentation page. To make this easy to use, it comes with a blueprint and the configuration options below:
+* `FPV_DOCS_SITE_NAME: str`: Your site's name, to be displayed in the page title, default: `Site`
+* `FPV_DOCS_CUSTOM_BLOCKS: array`: An array of dicts to display as cards at the top of your documentation, with the (optional) keys:
+  * `title: Optional[str]`: The title of the card
+  * `body: Optional[str] (HTML allowed)`: The body of the card
+  * `order: int`: The order in which to display this card (out of the other custom cards)
+* `FPV_DOCS_DEFAULT_THEME: str`: The default theme to display in the generated webpage
+
+#### Included Blueprint
+The documentation blueprint can be added using the following code:
+```py
+from flask_parameter_validation.docs_blueprint import docs_blueprint
+...
+app.register_blueprint(docs_blueprint)
+```
+
+The default blueprint adds two `GET` routes:
+* `/`: HTML Page with Bootstrap CSS and toggleable light/dark mode
+* `/json`: JSON Representation of the generated documentation
+
+The `/json` route yields a response with the following format:
+```json
+{
+  "custom_blocks": "<array entered in the FPV_DOCS_CUSTOM_BLOCKS config option, default: []>",
+  "default_theme": "<string entered in the FPV_DOCS_DEFAULT_THEME config option, default: 'light'>",
+  "docs": "<see get_docs_arr() return value format below>",
+  "site_name": "<string entered in the FPV_DOCS_SITE_NAME config option, default: 'Site'"
+}
+```
+
+##### Example with included Blueprint
+Code:
+```py
+@config_api.get("/")
+@ValidateParameters()
+def get_all_configs():
+    """
+    Get the System Configuration
+    Returns:
+    <code>{"configs":
+        [{"id": int,
+        "module": str,
+        "name": str,
+        "description": str,
+        "value": str}, ...]
+    }</code>
+    """
+    system_configs = []
+    for system_config in SystemConfig.query.all():
+        system_configs.append(system_config.toDict())
+    return resp_success({"configs": system_configs})
+
+
+@config_api.post("/<int:config_id>")
+@ValidateParameters()
+def edit_config(
+        config_id: int = Route(comment="The ID of the Config Record to Edit"),
+        value: str = Json(max_str_length=2000, comment="The value to set in the Config Record")
+):
+    """Edit a specific System Configuration value"""
+    config = SystemConfig.get_by_id(config_id)
+    if config is None:
+        return resp_not_found("No link exists with ID " + str(config_id))
+    else:
+        config.update(value)
+        return resp_success()
+```
+Documentation Generated:
+
+![](docs/api_documentation_example.png)
+
+#### Custom Blueprint
+If you would like to use your own blueprint, you can get the raw data from the following function:
+```py
+from flask_parameter_validation.docs_blueprint import get_docs_arr
+...
+get_docs_arr()
+```
+
+##### get_docs_arr() return value format
+This method returns an object with the following structure:
+
+```json
+[
+  {
+    "rule": "/path/to/route",
+    "methods": ["HTTPVerb"],
+    "docstring": "String, unsanitized of HTML Tags",
+    "args": {
+      "<Subclass of Parameter this route uses>": [
+        {
+          "name": "Argument Name",
+          "type": "Argument Type",
+          "loc_args": {
+            "<Name of argument passed to Parameter Subclass>": "Value passed to Argument",
+            "<Name of another argument passed to Parameter Subclass>": 0
+          }
+        }
+      ],
+      "<Another Subclass of Parameter this route uses>": []
+    }
+  },
+  ...
+]
+```

docs/api_documentation_example.png

@@ -0,0 +1,143 @@
+import flask
+from flask import Blueprint, current_app, jsonify
+
+from flask_parameter_validation import ValidateParameters
+
+docs_blueprint = Blueprint(
+    "docs", __name__, url_prefix="/docs", template_folder="./templates"
+)
+
+
+def get_route_docs():
+    """
+    Generate documentation for all Flask routes that use the ValidateParameters decorator.
+    Returns a list of dictionaries, each containing documentation for a particular route.
+    """
+    docs = []
+    for rule in current_app.url_map.iter_rules():  # Iterate through all Flask Routes
+        rule_func = current_app.view_functions[
+            rule.endpoint
+        ]  # Get the associated function
+        fn_docs = get_function_docs(rule_func)
+        if fn_docs:
+            fn_docs["rule"] = str(rule)
+            fn_docs["methods"] = [str(method) for method in rule.methods]
+            docs.append(fn_docs)
+    return docs
+
+
+def get_function_docs(func):
+    """
+    Get documentation for a specific function that uses the ValidateParameters decorator.
+    Returns a dictionary containing documentation details, or None if the decorator is not used.
+    """
+    fn_list = ValidateParameters().get_fn_list()
+    for fsig, fdocs in fn_list.items():
+        if fsig.endswith(func.__name__):
+            return {
+                "docstring": format_docstring(fdocs.get("docstring")),
+                "decorators": fdocs.get("decorators"),
+                "args": extract_argument_details(fdocs),
+            }
+    return None
+
+
+def format_docstring(docstring):
+    """
+    Format a function's docstring for HTML display.
+    """
+    if not docstring:
+        return None
+
+    docstring = docstring.strip().replace("\n", "<br/>")
+    return docstring.replace("    ", "&nbsp;" * 4)
+
+
+def extract_argument_details(fdocs):
+    """
+    Extract details about a function's arguments, including type hints and ValidateParameters details.
+    """
+    args_data = {}
+    for idx, arg_name in enumerate(fdocs["argspec"].args):
+        arg_data = {
+            "name": arg_name,
+            "type": get_arg_type_hint(fdocs, arg_name),
+            "loc": get_arg_location(fdocs, idx),
+            "loc_args": get_arg_location_details(fdocs, idx),
+        }
+        args_data.setdefault(arg_data["loc"], []).append(arg_data)
+    return args_data
+
+
+def get_arg_type_hint(fdocs, arg_name):
+    """
+    Extract the type hint for a specific argument.
+    """
+    arg_type = fdocs["argspec"].annotations[arg_name]
+    if hasattr(arg_type, "__args__"):
+        return (
+            f"{arg_type.__name__}[{', '.join([a.__name__ for a in arg_type.__args__])}]"
+        )
+    return arg_type.__name__
+
+
+def get_arg_location(fdocs, idx):
+    """
+    Determine where in the request the argument comes from (e.g., Route, Json, Query).
+    """
+    return type(fdocs["argspec"].defaults[idx]).__name__
+
+
+def get_arg_location_details(fdocs, idx):
+    """
+    Extract additional details about the location of an argument in the request.
+    """
+    loc_details = {}
+    location = fdocs["argspec"].defaults[idx]
+    for param, value in location.__dict__.items():
+        if value is not None:
+            if callable(value):
+                loc_details[param] = f"{value.__module__}.{value.__name__}"
+            else:
+                loc_details[param] = value
+    return loc_details
+
+
+@docs_blueprint.app_template_filter()
+def http_badge_bg(http_method):
+    """
+    Provide a color badge for various HTTP methods.
+    """
+    color_map = {"GET": "bg-primary", "POST": "bg-success", "DELETE": "bg-danger"}
+    return color_map.get(http_method, "bg-warning")
+
+
+@docs_blueprint.route("/")
+def docs_html():
+    """
+    Render the documentation as an HTML page.
+    """
+    config = flask.current_app.config
+    return flask.render_template(
+        "fpv_default_docs.html",
+        site_name=config.get("FPV_DOCS_SITE_NAME", "Site"),
+        docs=get_route_docs(),
+        custom_blocks=config.get("FPV_DOCS_CUSTOM_BLOCKS", []),
+        default_theme=config.get("FPV_DOCS_DEFAULT_THEME", "light"),
+    )
+
+
+@docs_blueprint.route("/json")
+def docs_json():
+    """
+    Provide the documentation as a JSON response.
+    """
+    config = flask.current_app.config
+    return jsonify(
+        {
+            "site_name": config.get("FPV_DOCS_SITE_NAME", "Site"),
+            "docs": get_route_docs(),
+            "custom_blocks": config.get("FPV_DOCS_CUSTOM_BLOCKS", []),
+            "default_theme": config.get("FPV_DOCS_DEFAULT_THEME", "light"),
+        }
+    )

flask_parameter_validation/docs_blueprint.py

@@ -25,7 +25,8 @@ def __init__(
         blacklist=None,  # str: character blacklist
         pattern=None,  # str: regexp pattern
         func=None,  # Callable -> Union[bool, tuple[bool, str]]: function performing a fully customized validation
-        datetime_format=None,  # str: datetime format string (https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)
+        datetime_format=None,  # str: datetime format string (https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes),
+        comment=None
     ):
         self.default = default
         self.min_list_length = min_list_length
@@ -39,6 +40,7 @@ def __init__(
         self.pattern = pattern
         self.func = func
         self.datetime_format = datetime_format
+        self.comment = comment
 
     # Validator
     def validate(self, value):

flask_parameter_validation/parameter_types/parameter.py

@@ -1,13 +1,19 @@
+import typing
+
 import re
 
 from .parameter_types import Route, Json, Query, Form, File
 from .exceptions import MissingInputError, InvalidParameterTypeError, ValidationError
-from flask import request
+from flask import request, current_app
 from inspect import signature
 from werkzeug.exceptions import BadRequest
+import inspect
 
-
+fn_list = dict()
 class ValidateParameters:
+    @classmethod
+    def get_fn_list(cls):
+        return fn_list
 
     def __init__(self, error_handler=None):
         self.custom_error_handler = error_handler
@@ -16,6 +22,17 @@ def __call__(self, f):
         """
         Parent flow for validating each required parameter
         """
+        fsig = f.__module__+"."+f.__name__
+        argspec = inspect.getfullargspec(f)
+        source = inspect.getsource(f)
+        index = source.find("def ")
+        decorators = []
+        for line in source[:index].strip().splitlines():
+            if line.strip()[0] == "@":
+                decorators.append(line)
+        fdocs = {"argspec": argspec, "docstring": f.__doc__.strip() if f.__doc__ else None, "decorators": decorators.copy()}
+        fn_list[fsig] = fdocs
+
         def nested_func(**kwargs):
             # Step 1 - Combine all flask input types to one dict
             json_input = None
@@ -165,3 +182,4 @@ def validate(self, expected_input, all_request_inputs):
         if len(user_inputs) == 1:
             return user_inputs[0]
         return user_inputs
+