FlexMeasures
diff --git a/‎.github/workflows/lint-and-test.yml‎
Lines changed: 1 addition & 1 deletion b/‎.github/workflows/lint-and-test.yml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.vscode/spellright.dict‎
Lines changed: 5 additions & 0 deletions b/‎.vscode/spellright.dict‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎Makefile‎
Lines changed: 7 additions & 1 deletion b/‎Makefile‎
Lines changed: 7 additions & 1 deletion
diff --git a/‎documentation/api/change_log.rst‎
Lines changed: 5 additions & 0 deletions b/‎documentation/api/change_log.rst‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎documentation/api/v3_0.rst‎
Lines changed: 27 additions & 5 deletions b/‎documentation/api/v3_0.rst‎
Lines changed: 27 additions & 5 deletions
diff --git a/‎documentation/changelog.rst‎
Lines changed: 1 addition & 0 deletions b/‎documentation/changelog.rst‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎documentation/conf.py‎
Lines changed: 1 addition & 0 deletions b/‎documentation/conf.py‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎flexmeasures/api/__init__.py‎
Lines changed: 69 additions & 21 deletions b/‎flexmeasures/api/__init__.py‎
Lines changed: 69 additions & 21 deletions
diff --git a/‎flexmeasures/api/common/schemas/assets.py‎
Lines changed: 25 additions & 0 deletions b/‎flexmeasures/api/common/schemas/assets.py‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎flexmeasures/api/common/schemas/generic_schemas.py‎
Lines changed: 15 additions & 0 deletions b/‎flexmeasures/api/common/schemas/generic_schemas.py‎
Lines changed: 15 additions & 0 deletions
@@ -85,7 +85,7 @@ jobs:
       # Label used to access the service container
       postgres:
         # Docker Hub image
-        image: postgres:12.5 
+        image: postgres:17.4 
         env:
           POSTGRES_USER: flexmeasures_test
           POSTGRES_PASSWORD: flexmeasures_test
 
@@ -292,3 +292,8 @@ asc
 desc
 autoflush
 fromisoformat
+upsample
+localhost
+schemas
+curtailable
+embeddable
@@ -5,7 +5,7 @@ HIGHS_DIR = "../HiGHS"
 
 # Note: use tabs
 # actions which are virtual, i.e. not a script
-.PHONY: install install-for-dev install-for-test install-deps install-flexmeasures test freeze-deps upgrade-deps update-docs update-docs-pdf show-file-space show-data-model clean-db cli-autocomplete build-highs-macos install-highs-macos
+.PHONY: install install-for-dev install-for-test install-deps install-flexmeasures test freeze-deps upgrade-deps update-docs update-docs-pdf generate-openapi show-file-space show-data-model clean-db cli-autocomplete build-highs-macos install-highs-macos
 
 
 # ---- Development ---
@@ -21,8 +21,10 @@ gen_code_docs := False # by default code documentation is not generated
 update-docs:
 	@echo "Creating docs environment ..."
 	make install-docs-dependencies
+	make generate-openapi
 	@echo "Creating documentation ..."
 	export FLEXMEASURES_ENV=documentation; export FLEXMEASURES_PLUGINS=; export GEN_CODE_DOCS=${gen_code_docs}; cd documentation; make clean; make html SPHINXOPTS="-W --keep-going -n"; cd ..
+	sed -i 's/(id)/id/g' flexmeasures/ui/static/documentation/html/api/v3_0.html # make sphinxcontrib-httpdomain links point to openapi-sphinx links
 
 update-docs-pdf:
 	@echo "NOTE: PDF documentation requires packages (on Debian: latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended)"
@@ -31,6 +33,10 @@ update-docs-pdf:
 	@echo "Creating documentation ..."
 	export FLEXMEASURES_ENV=documentation; export FLEXMEASURES_PLUGINS=; export GEN_CODE_DOCS=${gen_code_docs}; cd documentation; make clean; make latexpdf; make latexpdf; cd ..  # make latexpdf can require two passes
 
+generate-openapi:
+	@echo "Generating OpenAPI specifications..."
+	python flexmeasures/api/scripts/generate_open_api_specs.py
+
 # ---- Installation ---
 
 install: install-deps install-flexmeasures
 
@@ -5,6 +5,11 @@ API change log
 
 .. note:: The FlexMeasures API follows its own versioning scheme. This is also reflected in the URL (e.g. `/api/v3_0`), allowing developers to upgrade at their own pace.
 
+
+v3.0-28 | 2025-10-XX
+""""""""""""""""""""
+- Moved documentation to OpenAPI standard (incl. smaller improvements), each instance now provides a Swagger UI.
+
 v3.0-27 | 2025-09-16
 """"""""""""""""""""
 - Fix schema validation in ``PATCH /assets/<id>``.
 
@@ -1,20 +1,42 @@
 .. _v3_0:
 
 Version 3.0
-===========
+================
 
 Summary
 -------
 
+A quick overview of the available endpoints. For more details, click their names.
+
+.. The qrefs make links very similar to the openapi plugin, but we have to run a sed command after the fact to make them exactly alike (see Makefile)
 .. qrefflask:: flexmeasures.app:create(env="documentation")
     :modules: flexmeasures.api, flexmeasures.api.v3_0.assets, flexmeasures.api.v3_0.sensors, flexmeasures.api.v3_0.accounts, flexmeasures.api.v3_0.users, flexmeasures.api.v3_0.health, flexmeasures.api.v3_0.public
     :order: path
     :include-empty-docstring:
 
+
+OpenAPI & SwaggerUI
+-------------------
+
+We also provide interactive SwaggerUI documentation with each instance at `/api/v3_0/docs`. See a screenshot below.
+
+To access it, click on the book icon on the upper right or visit `https://<your-instance>/api/v3_0/docs`.
+If authenticated, you can try out the endpoints directly from there.
+
+.. image:: https://github.com/FlexMeasures/screenshots/raw/main/swagger-ui.png
+    :align: center
+
+|
+
+
 API Details
 -----------
 
-.. autoflask:: flexmeasures.app:create(env="documentation")
-    :modules: flexmeasures.api, flexmeasures.api.v3_0.assets, flexmeasures.api.v3_0.sensors, flexmeasures.api.v3_0.accounts, flexmeasures.api.v3_0.users, flexmeasures.api.v3_0.health, flexmeasures.api.v3_0.public
-    :order: path
-    :include-empty-docstring:
+Below, each endpoint is described in detail.
+
+.. we are using the specs which are located in the UI static folder, as that location is needed to serve it with each instance.
+.. openapi:: ../../flexmeasures/ui/static/openapi-specs.json
+    :format:
+      markdown
+    :group:
+    :examples:
@@ -72,6 +72,7 @@ New features
 * Improved timestamp on sensor detail page to be more friendly [see `PR #1632 <https://www.github.com/FlexMeasures/flexmeasures/pull/1632>`_]
 * Asset types support: new API endpoint (`GET /assets/types`), better docs and fix CLI command `flexmeasures show asset-types` [see `PR #1663 <https://github.com/FlexMeasures/flexmeasures/pull/1663>`_]
 * Add `--combine-legend` option to flexmeasures show chart. When used, all legends are combined and displayed at the bottom of the chart. If not used (default = False), each chart will display its own separate legend (as on the asset page) [see `PR #1696 <https://github.com/FlexMeasures/flexmeasures/pull/1696>`_]
+* Add support for using Swagger to generate API documentation [see `PR #1703 <https://github.com/FlexMeasures/flexmeasures/pull/1703>`_]
 
 Infrastructure / Support
 ----------------------
 
@@ -55,6 +55,7 @@
     "sphinxcontrib.autohttp.flask",
     "sphinxcontrib.autohttp.flaskqref",
     "sphinxcontrib.mermaid",
+    "sphinxcontrib.openapi",
 ]
 
 autodoc_default_options = {}
 
@@ -7,6 +7,7 @@
 from flask_security.utils import verify_password
 from flask_json import as_json
 from flask_login import current_user
+from webargs.flaskparser import use_args
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy import select
 
@@ -19,29 +20,46 @@
 )
 from flexmeasures.api.common.responses import invalid_sender
 from flexmeasures.data.schemas.utils import FMValidationError
+from flexmeasures.api.v3_0.users import AuthRequestSchema
 
 # The api blueprint. It is registered with the Flask app (see app.py)
 flexmeasures_api = Blueprint("flexmeasures_api", __name__)
 
 
 @flexmeasures_api.route("/requestAuthToken", methods=["POST"])
+@use_args(AuthRequestSchema, location="json")
 @as_json
-def request_auth_token():
-    """API endpoint to get a fresh authentication access token. Be aware that this fresh token has a limited lifetime
-    (which depends on the current system setting SECURITY_TOKEN_MAX_AGE).
-
-    Pass the `email` parameter to identify the user.
-    Pass the `password` parameter to authenticate the user (if not already authenticated in current session)
-
-    .. :quickref: Public; Obtain an authentication token
-    """
-
+def request_auth_token(args) -> tuple[dict, int]:
     """
-    The login of flask security returns the auth token, as well, but we'd like to
-     * skip authentication if the user is authenticated already
-     * be exempt from csrf protection (this is a JSON-only endpoint)
-     * use a more fitting name inside the api namespace
-     * return the information in a nicer structure
+    .. :quickref: Auth; Obtain authentication token
+    ---
+    post:
+      summary: Obtain a fresh authentication access token.
+      description: |
+          Retrieve a short-lived authentication token using email and password. The lifetime of this token depends on the current system setting
+          SECURITY_TOKEN_MAX_AGE.
+
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: AuthRequestSchema
+      responses:
+        200:
+          description: Token successfully generated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  authentication_token:
+                    type: string
+        400:
+          description: INVALID_REQUEST
+        401:
+          description: UNAUTHORIZED
+      tags:
+        - Auth
     """
     try:
         if not request.is_json:
@@ -80,15 +98,45 @@ def request_auth_token():
 @flexmeasures_api.route("/", methods=["GET"])
 @as_json
 def get_versions() -> dict:
-    """Public endpoint to list API versions.
-
+    """
     .. :quickref: Public; List available API versions
-
+    ---
+    get:
+      summary: List available API versions
+      description: |
+        Public endpoint to list all available FlexMeasures API versions.
+
+        This can be used to programmatically discover which API versions
+        are currently supported and their base URLs.
+      responses:
+        200:
+          description: Successfully retrieved available API versions.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: "For these API versions a public endpoint is available, listing its service."
+                  versions:
+                    type: array
+                    items:
+                      type: string
+                    example: ["v3_0"]
+                  flexmeasures_version:
+                    type: string
+                    example: "0.18.3"
+      tags:
+        - Public
     """
+
     response = {
-        "message": "For these API versions a public endpoint is available, listing its service. For example: "
-        "/api/v3_0. An authentication token can be requested at: "
-        "/api/requestAuthToken",
+        "message": (
+            "For these API versions a public endpoint is available, listing its service. For example: "
+            "/api/v3_0. An authentication token can be requested at: "
+            "/api/requestAuthToken"
+        ),
         "versions": ["v3_0"],
         "flexmeasures_version": flexmeasures_version,
     }
 
@@ -0,0 +1,25 @@
+from marshmallow import fields, validate
+
+from flexmeasures.api.common.schemas.generic_schemas import PaginationSchema
+from flexmeasures.api.common.schemas.users import AccountIdField
+
+
+class AssetAPIQuerySchema(PaginationSchema):
+    sort_by = fields.Str(
+        required=False,
+        validate=validate.OneOf(["id", "name", "owner"]),
+    )
+    account = AccountIdField(data_key="account_id", load_default=None)
+    all_accessible = fields.Bool(data_key="all_accessible", load_default=False)
+    include_public = fields.Bool(data_key="include_public", load_default=False)
+
+
+class AssetPaginationSchema(PaginationSchema):
+    sort_by = fields.Str(
+        required=False,
+        validate=validate.OneOf(["id", "name", "resolution"]),
+    )
+    sort_dir = fields.Str(
+        required=False,
+        validate=validate.OneOf(["asc", "desc"]),
+    )
@@ -0,0 +1,15 @@
+from marshmallow import Schema, fields, validate
+from flexmeasures.api.common.schemas.search import SearchFilterField
+
+
+class PaginationSchema(Schema):
+    # note: the absence of this parameter would signal to the API to not paginate (so there is no default set here)
+    page = fields.Int(required=False, validate=validate.Range(min=1))
+    per_page = fields.Int(
+        required=False, validate=validate.Range(min=1), load_default=10
+    )
+    filter = SearchFilterField(required=False)
+    sort_by = fields.Str(
+        required=False,
+    )
+    sort_dir = fields.Str(required=False, validate=validate.OneOf(["asc", "desc"]))
Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,7 @@`
`55`	`55`	`"sphinxcontrib.autohttp.flask",`
`56`	`56`	`"sphinxcontrib.autohttp.flaskqref",`
`57`	`57`	`"sphinxcontrib.mermaid",`
	`58`	`+ "sphinxcontrib.openapi",`
`58`	`59`	`]`
`59`	`60`
`60`	`61`	`autodoc_default_options = {}`