Bobby Noelte 94467e1a69 Add API documentation generation and use Markdown (#160)
* Add package API documentation generation

Add generation of the API documentation for akkudoktoreos
and akkudoktoreosserver packages.

The API documentation is generated by the Sphinx autosummary extension.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

* Enable Google style source commenting and documentation generation.

Enable automatic documentation generation from Google style docstrings in the source.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

* Check Google style source commenting.

Check Google style commenting by the appropriate ruff rules.

Commenting is _NOT_ enforced. Missing docstrings are ignored.

Minor commenting quirks of the code base are adapted.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

* Improve Markdown handling and switch to Markdown documentation.

Switch to Markdown for the documentation files to improve the user and developer experience (see issue #181).

Keep files with special directives for automatic API documentation in RST format. The
directives expect RST.

Also add dummy handling for openai/ swagger server documentation. The openai interface definition is
for now taken from the fastapi PR as EOS will switch to fastAPI.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

---------

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
Co-authored-by: Normann <github@koldrack.com>
2024-11-10 23:27:52 +01:00

921 lines
27 KiB
JSON

{
"openapi": "3.1.0",
"info": {
"title": "Akkudoktor-EOS",
"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.",
"version": "0.0.1"
},
"paths": {
"/strompreis": {
"get": {
"summary": "Fastapi Strompreis",
"operationId": "fastapi_strompreis_strompreis_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"items": {
"type": "number"
},
"type": "array",
"title": "Response Fastapi Strompreis Strompreis Get"
}
}
}
}
}
}
},
"/gesamtlast": {
"post": {
"summary": "Fastapi Gesamtlast",
"description": "Endpoint to handle total load calculation based on the latest measured data",
"operationId": "fastapi_gesamtlast_gesamtlast_post",
"parameters": [
{
"name": "year_energy",
"in": "query",
"required": true,
"schema": {
"type": "number",
"title": "Year Energy"
}
},
{
"name": "hours",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 48,
"title": "Hours"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
},
"title": "Measured Data"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "number"
},
"title": "Response Fastapi Gesamtlast Gesamtlast Post"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/gesamtlast_simple": {
"get": {
"summary": "Fastapi Gesamtlast Simple",
"operationId": "fastapi_gesamtlast_simple_gesamtlast_simple_get",
"parameters": [
{
"name": "year_energy",
"in": "query",
"required": true,
"schema": {
"type": "number",
"title": "Year Energy"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "number"
},
"title": "Response Fastapi Gesamtlast Simple Gesamtlast Simple Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/pvforecast": {
"get": {
"summary": "Fastapi Pvprognose",
"operationId": "fastapi_pvprognose_pvforecast_get",
"parameters": [
{
"name": "url",
"in": "query",
"required": true,
"schema": {
"type": "string",
"title": "Url"
}
},
{
"name": "ac_power_measurement",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Ac Power Measurement"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForecastResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/optimize": {
"post": {
"summary": "Fastapi Optimize",
"operationId": "fastapi_optimize_optimize_post",
"parameters": [
{
"name": "start_hour",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Defaults to current hour of the day.",
"title": "Start Hour"
},
"description": "Defaults to current hour of the day."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OptimizationParameters"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OptimizeResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/visualization_results.pdf": {
"get": {
"summary": "Get Pdf",
"operationId": "get_pdf_visualization_results_pdf_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
}
},
"components": {
"schemas": {
"EAutoParameters": {
"properties": {
"kapazitaet_wh": {
"type": "integer",
"exclusiveMinimum": 0.0,
"title": "Kapazitaet Wh",
"description": "An integer representing the capacity of the battery in watt-hours."
},
"lade_effizienz": {
"type": "number",
"maximum": 1.0,
"exclusiveMinimum": 0.0,
"title": "Lade Effizienz",
"description": "A float representing the charging efficiency of the battery.",
"default": 0.88
},
"entlade_effizienz": {
"type": "number",
"title": "Entlade Effizienz",
"default": 1.0
},
"max_ladeleistung_w": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0.0
},
{
"type": "null"
}
],
"title": "Max Ladeleistung W",
"description": "An integer representing the charging power of the battery in watts."
},
"start_soc_prozent": {
"type": "integer",
"maximum": 100.0,
"minimum": 0.0,
"title": "Start Soc Prozent",
"description": "An integer representing the current state of charge (SOC) of the battery in percentage.",
"default": 0
},
"min_soc_prozent": {
"type": "integer",
"maximum": 100.0,
"minimum": 0.0,
"title": "Min Soc Prozent",
"description": "An integer representing the minimum state of charge (SOC) of the battery in percentage.",
"default": 0
},
"max_soc_prozent": {
"type": "integer",
"maximum": 100.0,
"minimum": 0.0,
"title": "Max Soc Prozent",
"default": 100
}
},
"type": "object",
"required": [
"kapazitaet_wh"
],
"title": "EAutoParameters"
},
"EAutoResult": {
"properties": {
"charge_array": {
"items": {
"type": "number"
},
"type": "array",
"title": "Charge Array",
"description": "Indicates for each hour whether the EV is charging (`0` for no charging, `1` for charging)."
},
"discharge_array": {
"items": {
"type": "integer"
},
"type": "array",
"title": "Discharge Array",
"description": "Indicates for each hour whether the EV is discharging (`0` for no discharging, `1` for discharging)."
},
"entlade_effizienz": {
"type": "number",
"title": "Entlade Effizienz",
"description": "The discharge efficiency as a float."
},
"hours": {
"type": "integer",
"title": "Hours",
"default": "Amount of hours the simulation is done for."
},
"kapazitaet_wh": {
"type": "integer",
"title": "Kapazitaet Wh",
"default": "The capacity of the EV\u2019s battery in watt-hours."
},
"lade_effizienz": {
"type": "number",
"title": "Lade Effizienz",
"default": "The charging efficiency as a float."
},
"max_ladeleistung_w": {
"type": "integer",
"title": "Max Ladeleistung W",
"description": "The maximum charging power of the EV in watts."
},
"soc_wh": {
"type": "number",
"title": "Soc Wh",
"description": "The state of charge of the battery in watt-hours at the start of the simulation."
},
"start_soc_prozent": {
"type": "integer",
"title": "Start Soc Prozent",
"description": "The state of charge of the battery in percentage at the start of the simulation."
}
},
"type": "object",
"required": [
"charge_array",
"discharge_array",
"entlade_effizienz",
"max_ladeleistung_w",
"soc_wh",
"start_soc_prozent"
],
"title": "EAutoResult",
"description": "\"This object contains information related to the electric vehicle and its charging and discharging behavior"
},
"EnergieManagementSystemParameters": {
"properties": {
"pv_prognose_wh": {
"items": {
"type": "number"
},
"type": "array",
"title": "Pv Prognose Wh",
"description": "An array of floats representing the forecasted photovoltaic output in watts for different time intervals."
},
"strompreis_euro_pro_wh": {
"items": {
"type": "number"
},
"type": "array",
"title": "Strompreis Euro Pro Wh",
"description": "An array of floats representing the electricity price in euros per watt-hour for different time intervals."
},
"einspeiseverguetung_euro_pro_wh": {
"type": "number",
"title": "Einspeiseverguetung Euro Pro Wh",
"description": "A float representing the feed-in compensation in euros per watt-hour."
},
"preis_euro_pro_wh_akku": {
"type": "number",
"title": "Preis Euro Pro Wh Akku"
},
"gesamtlast": {
"items": {
"type": "number"
},
"type": "array",
"title": "Gesamtlast",
"description": "An array of floats representing the total load (consumption) in watts for different time intervals."
}
},
"type": "object",
"required": [
"pv_prognose_wh",
"strompreis_euro_pro_wh",
"einspeiseverguetung_euro_pro_wh",
"preis_euro_pro_wh_akku",
"gesamtlast"
],
"title": "EnergieManagementSystemParameters"
},
"ForecastResponse": {
"properties": {
"temperature": {
"items": {
"type": "number"
},
"type": "array",
"title": "Temperature"
},
"pvpower": {
"items": {
"type": "number"
},
"type": "array",
"title": "Pvpower"
}
},
"type": "object",
"required": [
"temperature",
"pvpower"
],
"title": "ForecastResponse"
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"HaushaltsgeraetParameters": {
"properties": {
"verbrauch_wh": {
"type": "integer",
"exclusiveMinimum": 0.0,
"title": "Verbrauch Wh",
"description": "An integer representing the energy consumption of a household device in watt-hours."
},
"dauer_h": {
"type": "integer",
"exclusiveMinimum": 0.0,
"title": "Dauer H",
"description": "An integer representing the usage duration of a household device in hours."
}
},
"type": "object",
"required": [
"verbrauch_wh",
"dauer_h"
],
"title": "HaushaltsgeraetParameters"
},
"OptimizationParameters": {
"properties": {
"ems": {
"$ref": "#/components/schemas/EnergieManagementSystemParameters"
},
"pv_akku": {
"$ref": "#/components/schemas/PVAkkuParameters"
},
"wechselrichter": {
"$ref": "#/components/schemas/WechselrichterParameters",
"default": {
"max_leistung_wh": 10000.0
}
},
"eauto": {
"$ref": "#/components/schemas/EAutoParameters"
},
"spuelmaschine": {
"anyOf": [
{
"$ref": "#/components/schemas/HaushaltsgeraetParameters"
},
{
"type": "null"
}
]
},
"temperature_forecast": {
"items": {
"type": "number"
},
"type": "array",
"title": "Temperature Forecast",
"default": "An array of floats representing the temperature forecast in degrees Celsius for different time intervals."
},
"start_solution": {
"anyOf": [
{
"items": {
"type": "number"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Start Solution",
"description": "Can be `null` or contain a previous solution (if available)."
}
},
"type": "object",
"required": [
"ems",
"pv_akku",
"eauto"
],
"title": "OptimizationParameters"
},
"OptimizeResponse": {
"properties": {
"discharge_hours_bin": {
"items": {
"type": "integer"
},
"type": "array",
"title": "Discharge Hours Bin",
"description": "An array that indicates for each hour of the forecast period whether energy is discharged from the battery or not. The values are either `0` (no discharge) or `1` (discharge)."
},
"eautocharge_hours_float": {
"items": {
"type": "number"
},
"type": "array",
"title": "Eautocharge Hours Float",
"description": "An array of binary values (0 or 1) that indicates whether the EV will be charged in a certain hour."
},
"result": {
"$ref": "#/components/schemas/SimulationResult"
},
"eauto_obj": {
"$ref": "#/components/schemas/EAutoResult"
},
"start_solution": {
"anyOf": [
{
"items": {
"type": "number"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Start Solution",
"description": "An array of binary values (0 or 1) representing a possible starting solution for the simulation."
},
"spuelstart": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Spuelstart",
"description": "Can be `null` or contain an object representing the start of washing (if applicable)."
}
},
"type": "object",
"required": [
"discharge_hours_bin",
"eautocharge_hours_float",
"result",
"eauto_obj"
],
"title": "OptimizeResponse",
"description": "**Note**: The first value of \"Last_Wh_pro_Stunde\", \"Netzeinspeisung_Wh_pro_Stunde\" and \"Netzbezug_Wh_pro_Stunde\", will be set to null in the JSON output and represented as NaN or None in the corresponding classes' data returns. This approach is adopted to ensure that the current hour's processing remains unchanged."
},
"PVAkkuParameters": {
"properties": {
"kapazitaet_wh": {
"type": "integer",
"exclusiveMinimum": 0.0,
"title": "Kapazitaet Wh",
"description": "An integer representing the capacity of the battery in watt-hours."
},
"lade_effizienz": {
"type": "number",
"maximum": 1.0,
"exclusiveMinimum": 0.0,
"title": "Lade Effizienz",
"description": "A float representing the charging efficiency of the battery.",
"default": 0.88
},
"entlade_effizienz": {
"type": "number",
"maximum": 1.0,
"exclusiveMinimum": 0.0,
"title": "Entlade Effizienz",
"default": 0.88
},
"max_ladeleistung_w": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0.0
},
{
"type": "null"
}
],
"title": "Max Ladeleistung W",
"description": "An integer representing the charging power of the battery in watts.",
"default": 5000
},
"start_soc_prozent": {
"type": "integer",
"maximum": 100.0,
"minimum": 0.0,
"title": "Start Soc Prozent",
"description": "An integer representing the state of charge of the battery at the **start** of the current hour (not the current state).",
"default": 0
},
"min_soc_prozent": {
"type": "integer",
"maximum": 100.0,
"minimum": 0.0,
"title": "Min Soc Prozent",
"description": "An integer representing the minimum state of charge (SOC) of the battery in percentage.",
"default": 0
},
"max_soc_prozent": {
"type": "integer",
"maximum": 100.0,
"minimum": 0.0,
"title": "Max Soc Prozent",
"default": 100
}
},
"type": "object",
"required": [
"kapazitaet_wh"
],
"title": "PVAkkuParameters"
},
"SimulationResult": {
"properties": {
"Last_Wh_pro_Stunde": {
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array",
"title": "Last Wh Pro Stunde",
"description": "TBD"
},
"EAuto_SoC_pro_Stunde": {
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array",
"title": "Eauto Soc Pro Stunde",
"description": "The state of charge of the EV for each hour."
},
"Einnahmen_Euro_pro_Stunde": {
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array",
"title": "Einnahmen Euro Pro Stunde",
"description": "The revenue from grid feed-in or other sources in euros per hour."
},
"Gesamt_Verluste": {
"type": "number",
"title": "Gesamt Verluste",
"description": "The total losses in watt-hours over the entire period."
},
"Gesamtbilanz_Euro": {
"type": "number",
"title": "Gesamtbilanz Euro",
"description": "The total balance of revenues minus costs in euros."
},
"Gesamteinnahmen_Euro": {
"type": "number",
"title": "Gesamteinnahmen Euro",
"description": "The total revenues in euros."
},
"Gesamtkosten_Euro": {
"type": "number",
"title": "Gesamtkosten Euro",
"description": "The total costs in euros."
},
"Haushaltsgeraet_wh_pro_stunde": {
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array",
"title": "Haushaltsgeraet Wh Pro Stunde",
"description": "The energy consumption of a household appliance in watt-hours per hour."
},
"Kosten_Euro_pro_Stunde": {
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array",
"title": "Kosten Euro Pro Stunde",
"description": "The costs in euros per hour."
},
"Netzbezug_Wh_pro_Stunde": {
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array",
"title": "Netzbezug Wh Pro Stunde",
"description": "The grid energy drawn in watt-hours per hour."
},
"Netzeinspeisung_Wh_pro_Stunde": {
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array",
"title": "Netzeinspeisung Wh Pro Stunde",
"description": "The energy fed into the grid in watt-hours per hour."
},
"Verluste_Pro_Stunde": {
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array",
"title": "Verluste Pro Stunde",
"description": "The losses in watt-hours per hour."
},
"akku_soc_pro_stunde": {
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array",
"title": "Akku Soc Pro Stunde",
"description": "The state of charge of the battery (not the EV) in percentage per hour."
}
},
"type": "object",
"required": [
"Last_Wh_pro_Stunde",
"EAuto_SoC_pro_Stunde",
"Einnahmen_Euro_pro_Stunde",
"Gesamt_Verluste",
"Gesamtbilanz_Euro",
"Gesamteinnahmen_Euro",
"Gesamtkosten_Euro",
"Haushaltsgeraet_wh_pro_stunde",
"Kosten_Euro_pro_Stunde",
"Netzbezug_Wh_pro_Stunde",
"Netzeinspeisung_Wh_pro_Stunde",
"Verluste_Pro_Stunde",
"akku_soc_pro_stunde"
],
"title": "SimulationResult",
"description": "This object contains the results of the simulation and provides insights into various parameters over the entire forecast period"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"WechselrichterParameters": {
"properties": {
"max_leistung_wh": {
"type": "number",
"exclusiveMinimum": 0.0,
"title": "Max Leistung Wh",
"default": 10000
}
},
"type": "object",
"title": "WechselrichterParameters"
}
}
}
}