🎨 Add version_display field to solver responses and update API documentation

Author: pcrespov

services/api-server/src/simcore_service_api_server/api/routes/solvers.py

@@ -25,6 +25,7 @@
 from ..dependencies.services import get_catalog_service, get_solver_service
 from ..dependencies.webserver_http import AuthSession, get_webserver_session
 from ._constants import (
+    FMSG_CHANGELOG_ADDED_IN_VERSION,
     FMSG_CHANGELOG_NEW_IN_VERSION,
     FMSG_CHANGELOG_REMOVED_IN_VERSION_FORMAT,
     create_route_description,
@@ -67,8 +68,6 @@ async def list_solvers(
     catalog_service: Annotated[CatalogService, Depends(get_catalog_service)],
     url_for: Annotated[Callable, Depends(get_reverse_url_mapper)],
 ):
-    """Lists all available solvers (latest version)"""
-
     services, _ = await catalog_service.list_latest_releases(
         filters=ServiceListFilters(service_type=ServiceType.COMPUTATIONAL),
     )
@@ -167,21 +166,25 @@ async def list_solvers_releases(
 @router.get(
     "/{solver_key:path}/latest",
     response_model=Solver,
-    summary="Get Latest Release of a Solver",
     responses=_SOLVER_STATUS_CODES,
+    description=create_route_description(
+        base="Gets latest release of a solver",
+        changelog=[
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.7.1", "`version_display` field in the response"
+            ),
+        ],
+    ),
 )
 async def get_solver(
     solver_key: SolverKeyId,
     solver_service: Annotated[SolverService, Depends(get_solver_service)],
     url_for: Annotated[Callable, Depends(get_reverse_url_mapper)],
 ):
-    """Gets latest release of a solver"""
     # IMPORTANT: by adding /latest, we avoid changing the order of this entry in the router list
     # otherwise, {solver_key:path} will override and consume any of the paths that follow.
     try:
-        solver = await solver_service.get_latest_release(
-            solver_key=solver_key,
-        )
+        solver = await solver_service.get_latest_release(solver_key=solver_key)
         solver.url = url_for(
             "get_solver_release", solver_key=solver.id, version=solver.version
         )
@@ -199,16 +202,20 @@ async def get_solver(
     "/{solver_key:path}/releases",
     response_model=list[Solver],
     responses=_SOLVER_STATUS_CODES,
+    description=create_route_description(
+        base="Lists all releases of a given (one) solver",
+        changelog=[
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.7.1", "`version_display` field in the response"
+            ),
+        ],
+    ),
 )
 async def list_solver_releases(
     solver_key: SolverKeyId,
     solver_service: Annotated[SolverService, Depends(get_solver_service)],
     url_for: Annotated[Callable, Depends(get_reverse_url_mapper)],
 ):
-    """Lists all releases of a given (one) solver
-
-    SEE get_solver_releases_page for a paginated version of this function
-    """
     all_releases: list[Solver] = []
     for page_params in iter_pagination_params(limit=DEFAULT_PAGINATION_LIMIT):
         solvers, page_meta = await solver_service.solver_release_history(
@@ -267,14 +274,21 @@ async def get_solver_releases_page(
     "/{solver_key:path}/releases/{version}",
     response_model=Solver,
     responses=_SOLVER_STATUS_CODES,
+    description=create_route_description(
+        base="Gets a specific release of a solver",
+        changelog=[
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.7.1", "`version_display` field in the response"
+            ),
+        ],
+    ),
 )
 async def get_solver_release(
     solver_key: SolverKeyId,
     version: VersionStr,
     solver_service: Annotated[SolverService, Depends(get_solver_service)],
     url_for: Annotated[Callable, Depends(get_reverse_url_mapper)],
 ):
-    """Gets a specific release of a solver"""
     try:
         solver: Solver = await solver_service.get_solver(
             solver_key=solver_key,
@@ -302,8 +316,15 @@ async def get_solver_release(
     "/{solver_key:path}/releases/{version}/ports",
     response_model=OnePage[SolverPort],
     responses=_SOLVER_STATUS_CODES,
-    description="Lists inputs and outputs of a given solver\n\n"
-    + FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0"),
+    description=create_route_description(
+        base="Lists inputs and outputs of a given solver",
+        changelog=[
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0"),
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.7.1", "`version_display` field in the response"
+            ),
+        ],
+    ),
 )
 async def list_solver_ports(
     solver_key: SolverKeyId,
@@ -322,9 +343,16 @@ async def list_solver_ports(
 @router.get(
     "/{solver_key:path}/releases/{version}/pricing_plan",
     response_model=ServicePricingPlanGetLegacy,
-    description="Gets solver pricing plan\n\n"
-    + FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
     responses=_SOLVER_STATUS_CODES,
+    description=create_route_description(
+        base="Gets solver pricing plan",
+        changelog=[
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.7.1", "`version_display` field in the response"
+            ),
+        ],
+    ),
 )
 async def get_solver_pricing_plan(
     solver_key: SolverKeyId,

services/api-server/tests/unit/api_solvers/test_api_routers_solvers.py

@@ -6,64 +6,84 @@
 
 
 import httpx
-import pytest
-import simcore_service_api_server.api.routes.solvers
+from api_solvers.conftest import solver_version
 from pydantic import TypeAdapter
-from pytest_mock import MockFixture
+from pytest_mock import MockType
 from simcore_service_api_server._meta import API_VTAG
 from simcore_service_api_server.models.pagination import OnePage
 from simcore_service_api_server.models.schemas.solvers import Solver, SolverPort
 from starlette import status
 
 
-@pytest.mark.skip(reason="Still under development. Currently using fake implementation")
-async def test_list_solvers(
+async def test_list_all_solvers(
+    mocked_catalog_rpc_api: dict[str, MockType],
     client: httpx.AsyncClient,
-    mocker: MockFixture,
+    auth: httpx.BasicAuth,
 ):
-    warn = mocker.patch.object(
-        simcore_service_api_server.api.routes.solvers._logger, "warning"
-    )
+    response = await client.get(f"/{API_VTAG}/solvers", auth=auth)
+    assert response.status_code == status.HTTP_200_OK
 
-    # list solvers latest releases
-    resp = await client.get("/v0/solvers")
-    assert resp.status_code == status.HTTP_200_OK
 
-    # No warnings for ValidationError with the fixture
-    assert (
-        not warn.called
-    ), f"No warnings expected in this fixture, got {warn.call_args!s}"
+async def test_list_all_solvers_paginated(
+    mocked_catalog_rpc_api: dict[str, MockType],
+    client: httpx.AsyncClient,
+    auth: httpx.BasicAuth,
+):
+    response = await client.get(f"/{API_VTAG}/solvers/page", auth=auth)
+    assert response.status_code == status.HTTP_200_OK
+    assert len(response.json()["items"]) == response.json()["total"]
 
-    data = resp.json()
-    assert len(data) == 2
 
-    for item in data:
-        solver = Solver(**item)
-        print(solver.model_dump_json(indent=1, exclude_unset=True))
+async def test_list_all_solvers_releases(
+    mocked_catalog_rpc_api: dict[str, MockType],
+    client: httpx.AsyncClient,
+    auth: httpx.BasicAuth,
+):
+    response = await client.get(f"/{API_VTAG}/solvers/releases", auth=auth)
+    assert response.status_code == status.HTTP_200_OK
 
-        # use link to get the same solver
-        assert solver.url
-        assert solver.url.host == "api.testserver.io"  # cli.base_url
-        assert solver.url.path
 
-        # get_solver_latest_version_by_name
-        resp0 = await client.get(solver.url.path)
-        assert resp0.status_code == status.HTTP_501_NOT_IMPLEMENTED
-        assert f"GET solver {solver.id}" in resp0.json()["errors"][0]
-        # get_solver
-        resp1 = await client.get(f"/v0/solvers/{solver.id}")
-        assert resp1.status_code == status.HTTP_501_NOT_IMPLEMENTED
-        assert f"GET solver {solver.id}" in resp1.json()["errors"][0]
+async def test_list_all_solvers_releases_paginated(
+    mocked_catalog_rpc_api: dict[str, MockType],
+    client: httpx.AsyncClient,
+    auth: httpx.BasicAuth,
+):
+    solver_key = "simcore/services/comp/itis/sleeper"
+    response = await client.get(
+        f"/{API_VTAG}/solvers/{solver_key}/releases/page", auth=auth
+    )
+    assert response.status_code == status.HTTP_200_OK
+    assert len(response.json()["items"]) == response.json()["total"]
+
+
+async def test_list_solver_releases(
+    mocked_catalog_rpc_api: dict[str, MockType],
+    client: httpx.AsyncClient,
+    auth: httpx.BasicAuth,
+):
+    solver_key = "simcore/services/comp/itis/sleeper"
+    response = await client.get(f"/{API_VTAG}/solvers/{solver_key}/releases", auth=auth)
+    assert response.status_code == status.HTTP_200_OK
+
 
-        # get_solver_latest_version_by_name
-        resp2 = await client.get(f"/v0/solvers/{solver.id}/latest")
+async def test_get_solver_release(
+    mocked_catalog_rpc_api: dict[str, MockType],
+    client: httpx.AsyncClient,
+    auth: httpx.BasicAuth,
+):
+    solver_key = "simcore/services/comp/itis/sleeper"
+    solver_version = "2.2.1"
+    response = await client.get(
+        f"/{API_VTAG}/solvers/{solver_key}/releases/{solver_version}", auth=auth
+    )
+    assert response.status_code == status.HTTP_200_OK
 
-        assert resp2.status_code == status.HTTP_501_NOT_IMPLEMENTED
-        assert f"GET latest {solver.id}" in resp2.json()["errors"][0]
+    solver = Solver.model_validate(response.json())
+    assert solver.version_display == "2 Xtreme"
 
 
 async def test_list_solver_ports(
-    mocked_catalog_rpc_api: dict,
+    mocked_catalog_rpc_api: dict[str, MockType],
     client: httpx.AsyncClient,
     auth: httpx.BasicAuth,
 ):
@@ -100,60 +120,9 @@ async def test_list_solver_ports(
     }
 
 
-async def test_list_solvers_with_mocked_catalog(
-    client: httpx.AsyncClient,
-    mocked_catalog_rpc_api: dict,
-    auth: httpx.BasicAuth,
-):
-    response = await client.get(f"/{API_VTAG}/solvers", auth=auth)
-    assert response.status_code == status.HTTP_200_OK
-
-
-async def test_list_releases_with_mocked_catalog(
-    client: httpx.AsyncClient,
-    mocked_catalog_rpc_api: dict,
-    auth: httpx.BasicAuth,
-):
-    response = await client.get(f"/{API_VTAG}/solvers/releases", auth=auth)
-    assert response.status_code == status.HTTP_200_OK
-
-
-async def test_list_solver_page_with_mocked_catalog(
-    client: httpx.AsyncClient,
-    mocked_catalog_rpc_api: dict,
-    auth: httpx.BasicAuth,
-):
-    response = await client.get(f"/{API_VTAG}/solvers/page", auth=auth)
-    assert response.status_code == status.HTTP_200_OK
-    assert len(response.json()["items"]) == response.json()["total"]
-
-
-async def test_list_solver_releases_page_with_mocked_catalog(
-    client: httpx.AsyncClient,
-    mocked_catalog_rpc_api: dict,
-    auth: httpx.BasicAuth,
-):
-    solver_key = "simcore/services/comp/itis/sleeper"
-    response = await client.get(
-        f"/{API_VTAG}/solvers/{solver_key}/releases/page", auth=auth
-    )
-    assert response.status_code == status.HTTP_200_OK
-    assert len(response.json()["items"]) == response.json()["total"]
-
-
-async def test_list_solver_releases_with_mocked_catalog(
-    client: httpx.AsyncClient,
-    mocked_catalog_rpc_api: dict,
-    auth: httpx.BasicAuth,
-):
-    solver_key = "simcore/services/comp/itis/sleeper"
-    response = await client.get(f"/{API_VTAG}/solvers/{solver_key}/releases", auth=auth)
-    assert response.status_code == status.HTTP_200_OK
-
-
-async def test_list_solver_ports_with_mocked_catalog(
+async def test_list_solver_ports_again(
+    mocked_catalog_rpc_api: dict[str, MockType],
     client: httpx.AsyncClient,
-    mocked_catalog_rpc_api: dict,
     auth: httpx.BasicAuth,
 ):
     solver_key = "simcore/services/comp/itis/sleeper"