Add documentation. (#321)

Add documentation that covers: - Prediction - Measuremnt - REST API Add Python scripts that support automatic documentation generation using the Sphinx sphinxcontrib.eval extension. Add automatic update/ test for REST API documentation. Filter proxy endpoints from REST API documentation. Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
2025-09-13 07:21:16 +00:00 · 2025-01-03 00:31:20 +01:00
parent 4cb6dc7270
commit 1866055478
27 changed files with 7565 additions and 6131 deletions
--- a/tests/generate_openapi.py
+++ b/tests/generate_openapi.py
@@ -1,25 +0,0 @@
-import json
-from pathlib import Path
-
-from fastapi.openapi.utils import get_openapi
-
-from akkudoktoreos.server.fastapi_server import app
-
-
-def generate_openapi(filename: str | Path = "openapi.json"):
-    with open(filename, "w") as f:
-        json.dump(
-            get_openapi(
-                title=app.title,
-                version=app.version,
-                openapi_version=app.openapi_version,
-                description=app.description,
-                routes=app.routes,
-            ),
-            f,
-            indent=2,
-        )
-
-
-if __name__ == "__main__":
-    generate_openapi()
--- a/tests/test_openapi.py
+++ b/tests/test_openapi.py
@@ -1,27 +1,56 @@
 import json
+import sys
 from pathlib import Path
 from unittest.mock import patch

+import pytest
+
 DIR_PROJECT_ROOT = Path(__file__).parent.parent
 DIR_TESTDATA = Path(__file__).parent / "testdata"


 def test_openapi_spec_current(config_eos):
    """Verify the openapi spec hasn´t changed."""
-    old_spec_path = DIR_PROJECT_ROOT / "docs" / "akkudoktoreos" / "openapi.json"
+    expected_spec_path = DIR_PROJECT_ROOT / "openapi.json"
    new_spec_path = DIR_TESTDATA / "openapi-new.json"
+    expected_spec_md_path = DIR_TESTDATA / "openapi.md"
+    new_spec_md_path = DIR_TESTDATA / "openapi-new.md"
+
+    with open(expected_spec_path) as f_expected:
+        expected_spec = json.load(f_expected)
+    with open(expected_spec_md_path) as f_expected:
+        expected_spec_md = f_expected.read()
+
    # Patch get_config and import within guard to patch global variables within the fastapi_server module.
    with patch("akkudoktoreos.config.config.get_config", return_value=config_eos):
-        from generate_openapi import generate_openapi
+        # Ensure the script works correctly as part of a package
+        root_dir = Path(__file__).resolve().parent.parent
+        sys.path.insert(0, str(root_dir))
+        from scripts import generate_openapi, generate_openapi_md

-        generate_openapi(new_spec_path)
-    with open(new_spec_path) as f_new:
-        new_spec = json.load(f_new)
-    with open(old_spec_path) as f_old:
-        old_spec = json.load(f_old)
+        spec = generate_openapi.generate_openapi()
+        spec_md = generate_openapi_md.generate_openapi_md()
+
+    with open(new_spec_path, "w") as f_new:
+        json.dump(spec, f_new, indent=4, sort_keys=True)
+    with open(new_spec_md_path, "w") as f_new:
+        f_new.write(spec_md)

    # Serialize to ensure comparison is consistent
-    new_spec = json.dumps(new_spec, indent=4, sort_keys=True)
-    old_spec = json.dumps(old_spec, indent=4, sort_keys=True)
+    spec_str = json.dumps(spec, indent=4, sort_keys=True)
+    expected_spec_str = json.dumps(expected_spec, indent=4, sort_keys=True)

-    assert new_spec == old_spec
+    try:
+        assert spec_str == expected_spec_str
+    except AssertionError as e:
+        pytest.fail(
+            f"Expected {new_spec_path} to equal {expected_spec_path}.\n"
+            + f"If ok: cp {new_spec_path} {expected_spec_path}\n"
+        )
+    try:
+        assert spec_md == expected_spec_md
+    except AssertionError as e:
+        pytest.fail(
+            f"Expected {new_spec_md_path} to equal {expected_spec_md_path}.\n"
+            + f"If ok: cp {new_spec_md_path} {expected_spec_md_path}\n"
+        )
--- a/tests/testdata/openapi.md
+++ b/tests/testdata/openapi.md
@@ -0,0 +1,569 @@
+# Akkudoktor-EOS
+
+**Version**: `0.0.1`
+
+**Description**: This project provides a comprehensive solution for simulating and optimizing an energy system based on renewable energy sources. With a focus on photovoltaic (PV) systems, battery storage (batteries), load management (consumer requirements), heat pumps, electric vehicles, and consideration of electricity price data, this system enables forecasting and optimization of energy flow and costs over a specified period.
+
+**Base URL**: `No base URL provided.`
+
+**Endpoints**:
+
+## GET /v1/config
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_get_v1_config_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_get_v1_config_get)
+
+Fastapi Config Get
+
+```
+Get the current configuration.
+```
+
+**Responses**:
+
+- **200**: Successful Response
+
+---
+
+## PUT /v1/config
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_put_v1_config_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_put_v1_config_put)
+
+Fastapi Config Put
+
+```
+Merge settings into current configuration.
+
+Args:
+    settings (SettingsEOS): The settings to merge into the current configuration.
+    save (Optional[bool]): Save the resulting configuration to the configuration file.
+        Defaults to False.
+```
+
+**Parameters**:
+
+- `save` (query, optional): No description provided.
+
+**Request Body**:
+
+- `application/json`: {
+  "$ref": "#/components/schemas/SettingsEOS"
+}
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## GET /v1/measurement/keys
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_keys_get_v1_measurement_keys_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_keys_get_v1_measurement_keys_get)
+
+Fastapi Measurement Keys Get
+
+```
+Get a list of available measurement keys.
+```
+
+**Responses**:
+
+- **200**: Successful Response
+
+---
+
+## GET /v1/measurement/load-mr/series/by-name
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_load_mr_series_by_name_get_v1_measurement_load-mr_series_by-name_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_load_mr_series_by_name_get_v1_measurement_load-mr_series_by-name_get)
+
+Fastapi Measurement Load Mr Series By Name Get
+
+```
+Get the meter reading of given load name as series.
+```
+
+**Parameters**:
+
+- `name` (query, required): Load name.
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## PUT /v1/measurement/load-mr/series/by-name
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_load_mr_series_by_name_put_v1_measurement_load-mr_series_by-name_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_load_mr_series_by_name_put_v1_measurement_load-mr_series_by-name_put)
+
+Fastapi Measurement Load Mr Series By Name Put
+
+```
+Merge the meter readings series of given load name into EOS measurements at given datetime.
+```
+
+**Parameters**:
+
+- `name` (query, required): Load name.
+
+**Request Body**:
+
+- `application/json`: {
+  "$ref": "#/components/schemas/PydanticDateTimeSeries"
+}
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## PUT /v1/measurement/load-mr/value/by-name
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_load_mr_value_by_name_put_v1_measurement_load-mr_value_by-name_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_load_mr_value_by_name_put_v1_measurement_load-mr_value_by-name_put)
+
+Fastapi Measurement Load Mr Value By Name Put
+
+```
+Merge the meter reading of given load name and value into EOS measurements at given datetime.
+```
+
+**Parameters**:
+
+- `datetime` (query, required): Datetime.
+
+- `name` (query, required): Load name.
+
+- `value` (query, required): No description provided.
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## GET /v1/measurement/series
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_series_get_v1_measurement_series_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_series_get_v1_measurement_series_get)
+
+Fastapi Measurement Series Get
+
+```
+Get the measurements of given key as series.
+```
+
+**Parameters**:
+
+- `key` (query, required): Prediction key.
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## PUT /v1/measurement/series
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_series_put_v1_measurement_series_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_series_put_v1_measurement_series_put)
+
+Fastapi Measurement Series Put
+
+```
+Merge measurement given as series into given key.
+```
+
+**Parameters**:
+
+- `key` (query, required): Prediction key.
+
+**Request Body**:
+
+- `application/json`: {
+  "$ref": "#/components/schemas/PydanticDateTimeSeries"
+}
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## PUT /v1/measurement/value
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_value_put_v1_measurement_value_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_value_put_v1_measurement_value_put)
+
+Fastapi Measurement Value Put
+
+```
+Merge the measurement of given key and value into EOS measurements at given datetime.
+```
+
+**Parameters**:
+
+- `datetime` (query, required): Datetime.
+
+- `key` (query, required): Prediction key.
+
+- `value` (query, required): No description provided.
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## PUT /v1/measurement/dataframe
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_dataframe_put_v1_measurement_dataframe_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_dataframe_put_v1_measurement_dataframe_put)
+
+Fastapi Measurement Dataframe Put
+
+```
+Merge the measurement data given as dataframe into EOS measurements.
+```
+
+**Request Body**:
+
+- `application/json`: {
+  "$ref": "#/components/schemas/PydanticDateTimeDataFrame"
+}
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## PUT /v1/measurement/data
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_data_put_v1_measurement_data_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_data_put_v1_measurement_data_put)
+
+Fastapi Measurement Data Put
+
+```
+Merge the measurement data given as datetime data into EOS measurements.
+```
+
+**Request Body**:
+
+- `application/json`: {
+  "$ref": "#/components/schemas/PydanticDateTimeData"
+}
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## GET /v1/prediction/keys
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_keys_get_v1_prediction_keys_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_keys_get_v1_prediction_keys_get)
+
+Fastapi Prediction Keys Get
+
+```
+Get a list of available prediction keys.
+```
+
+**Responses**:
+
+- **200**: Successful Response
+
+---
+
+## GET /v1/prediction/series
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_series_get_v1_prediction_series_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_series_get_v1_prediction_series_get)
+
+Fastapi Prediction Series Get
+
+```
+Get prediction for given key within given date range as series.
+
+Args:
+    key (str): Prediction key
+    start_datetime (Optional[str]): Starting datetime (inclusive).
+        Defaults to start datetime of latest prediction.
+    end_datetime (Optional[str]: Ending datetime (exclusive).
+        Defaults to end datetime of latest prediction.
+```
+
+**Parameters**:
+
+- `key` (query, required): Prediction key.
+
+- `start_datetime` (query, optional): Starting datetime (inclusive).
+
+- `end_datetime` (query, optional): Ending datetime (exclusive).
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## GET /v1/prediction/list
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_list_get_v1_prediction_list_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_list_get_v1_prediction_list_get)
+
+Fastapi Prediction List Get
+
+```
+Get prediction for given key within given date range as value list.
+
+Args:
+    key (str): Prediction key
+    start_datetime (Optional[str]): Starting datetime (inclusive).
+        Defaults to start datetime of latest prediction.
+    end_datetime (Optional[str]: Ending datetime (exclusive).
+        Defaults to end datetime of latest prediction.
+    interval (Optional[str]): Time duration for each interval.
+        Defaults to 1 hour.
+```
+
+**Parameters**:
+
+- `key` (query, required): Prediction key.
+
+- `start_datetime` (query, optional): Starting datetime (inclusive).
+
+- `end_datetime` (query, optional): Ending datetime (exclusive).
+
+- `interval` (query, optional): Time duration for each interval.
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## POST /v1/prediction/update
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_update_v1_prediction_update_post), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_update_v1_prediction_update_post)
+
+Fastapi Prediction Update
+
+```
+Update predictions for all providers.
+
+Args:
+    force_update: Update data even if it is already cached.
+        Defaults to False.
+    force_enable: Update data even if provider is disabled.
+        Defaults to False.
+```
+
+**Parameters**:
+
+- `force_update` (query, optional): No description provided.
+
+- `force_enable` (query, optional): No description provided.
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## POST /v1/prediction/update/{provider_id}
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_update_provider_v1_prediction_update__provider_id__post), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_update_provider_v1_prediction_update__provider_id__post)
+
+Fastapi Prediction Update Provider
+
+```
+Update predictions for given provider ID.
+
+Args:
+    provider_id: ID of provider to update.
+    force_update: Update data even if it is already cached.
+        Defaults to False.
+    force_enable: Update data even if provider is disabled.
+        Defaults to False.
+```
+
+**Parameters**:
+
+- `provider_id` (path, required): No description provided.
+
+- `force_update` (query, optional): No description provided.
+
+- `force_enable` (query, optional): No description provided.
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## GET /strompreis
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_strompreis_strompreis_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_strompreis_strompreis_get)
+
+Fastapi Strompreis
+
+```
+Deprecated: Electricity Market Price Prediction per Wh (€/Wh).
+
+Note:
+    Set ElecPriceAkkudoktor as elecprice_provider, then update data with
+    '/v1/prediction/update'
+    and then request data with
+    '/v1/prediction/list?key=elecprice_marketprice_wh' or
+    '/v1/prediction/list?key=elecprice_marketprice_kwh' instead.
+```
+
+**Responses**:
+
+- **200**: Successful Response
+
+---
+
+## POST /gesamtlast
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_gesamtlast_gesamtlast_post), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_gesamtlast_gesamtlast_post)
+
+Fastapi Gesamtlast
+
+```
+Deprecated: Total Load Prediction with adjustment.
+
+Endpoint to handle total load prediction adjusted by latest measured data.
+
+Note:
+    Use '/v1/prediction/list?key=load_mean_adjusted' instead.
+    Load energy meter readings to be added to EOS measurement by:
+    '/v1/measurement/load-mr/value/by-name' or
+    '/v1/measurement/value'
+```
+
+**Request Body**:
+
+- `application/json`: {
+  "$ref": "#/components/schemas/GesamtlastRequest"
+}
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## GET /gesamtlast_simple
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_gesamtlast_simple_gesamtlast_simple_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_gesamtlast_simple_gesamtlast_simple_get)
+
+Fastapi Gesamtlast Simple
+
+```
+Deprecated: Total Load Prediction.
+
+Endpoint to handle total load prediction.
+
+Note:
+    Set LoadAkkudoktor as load_provider, then update data with
+    '/v1/prediction/update'
+    and then request data with
+    '/v1/prediction/list?key=load_mean' instead.
+```
+
+**Parameters**:
+
+- `year_energy` (query, required): No description provided.
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## GET /pvforecast
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_pvforecast_pvforecast_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_pvforecast_pvforecast_get)
+
+Fastapi Pvforecast
+
+```
+Deprecated: PV Forecast Prediction.
+
+Endpoint to handle PV forecast prediction.
+
+Note:
+    Set PVForecastAkkudoktor as pvforecast_provider, then update data with
+    '/v1/prediction/update'
+    and then request data with
+    '/v1/prediction/list?key=pvforecast_ac_power' and
+    '/v1/prediction/list?key=pvforecastakkudoktor_temp_air' instead.
+```
+
+**Responses**:
+
+- **200**: Successful Response
+
+---
+
+## POST /optimize
+
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_optimize_optimize_post), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_optimize_optimize_post)
+
+Fastapi Optimize
+
+**Parameters**:
+
+- `start_hour` (query, optional): Defaults to current hour of the day.
+
+**Request Body**:
+
+- `application/json`: {
+  "$ref": "#/components/schemas/OptimizationParameters"
+}
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
+## GET /visualization_results.pdf
+
+**Links**: [local](http://localhost:8503/docs#/default/get_pdf_visualization_results_pdf_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/get_pdf_visualization_results_pdf_get)
+
+Get Pdf
+
+**Responses**:
+
+- **200**: Successful Response
+
+---