🎨 public-api: cleanup openapi routes descriptions

services/api-server/openapi.json

@@ -1423,7 +1423,7 @@
           "solvers"
         ],
         "summary": "List Solvers",
-        "description": "\ud83d\udea8 **Deprecated**: This endpoint is deprecated and will be removed in a future release.\nPlease use `GET /v0/solvers/page` instead.\n\n\n\nLists all available solvers (latest version)\n\nNew in *version 0.5.0*",
+        "description": "\ud83d\udea8 **Deprecated**: This endpoint is deprecated and will be removed in a future release.\nPlease use `GET /v0/solvers/page` instead.\n\n\n\nLists all available solvers (latest version)\n\nNew in *version 0.5*",
         "operationId": "list_solvers",
         "responses": {
           "200": {
@@ -1514,7 +1514,7 @@
           "solvers"
         ],
         "summary": "Lists All Releases",
-        "description": "\ud83d\udea8 **Deprecated**: This endpoint is deprecated and will be removed in a future release.\nPlease use `GET /v0/solvers/{solver_key}/releases/page` instead.\n\n\n\nLists all released solvers (not just latest version)\n\nNew in *version 0.5.0*",
+        "description": "\ud83d\udea8 **Deprecated**: This endpoint is deprecated and will be removed in a future release.\nPlease use `GET /v0/solvers/{solver_key}/releases/page` instead.\n\n\n\nLists **all** released solvers (not just latest version)\n\nNew in *version 0.5*",
         "operationId": "list_solvers_releases",
         "responses": {
           "200": {
@@ -1946,7 +1946,7 @@
           "solvers"
         ],
         "summary": "List Solver Ports",
-        "description": "Lists inputs and outputs of a given solver\n\nNew in *version 0.5.0*\n\nAdded in *version 0.7.1*: `version_display` field in the response",
+        "description": "Lists inputs and outputs of a given solver\n\nNew in *version 0.5*\n\nAdded in *version 0.7.1*: `version_display` field in the response",
         "operationId": "list_solver_ports",
         "security": [
           {
@@ -2184,7 +2184,7 @@
           "solvers"
         ],
         "summary": "Create Solver Job",
-        "description": "Creates a job in a specific release with given inputs.\n\nNOTE: This operation does **not** start the job",
+        "description": "Creates a job in a specific release with given inputs. This operation does not start the job.\n\nNew in *version 0.5*",
         "operationId": "create_solver_job",
         "security": [
           {
@@ -2767,7 +2767,7 @@
           "solvers"
         ],
         "summary": "Start Job",
-        "description": "Starts job job_id created with the solver solver_key:version\n\nAdded in *version 0.4.3*: query parameter `cluster_id`\nAdded in *version 0.6*: responds with a 202 when successfully starting a computation\nChanged in *version 0.8*: query parameter `cluster_id` deprecated",
+        "description": "Starts job job_id created with the solver solver_key:version\n\nAdded in *version 0.4.3*: query parameter `cluster_id`\n\nAdded in *version 0.6*: responds with a 202 when successfully starting a computation\n\nChanged in *version 0.7*: query parameter `cluster_id` deprecated",
         "operationId": "start_job",
         "security": [
           {
@@ -2945,6 +2945,7 @@
           "solvers"
         ],
         "summary": "Stop Job",
+        "description": "Stops a running job\n\nNew in *version 0.5*",
         "operationId": "stop_job",
         "security": [
           {
@@ -3083,6 +3084,7 @@
           "solvers"
         ],
         "summary": "Inspect Job",
+        "description": "Inspects the current status of a job\n\nNew in *version 0.5*",
         "operationId": "inspect_job",
         "security": [
           {
@@ -3486,9 +3488,9 @@
         "tags": [
           "solvers"
         ],
-        "summary": "Get Jobs Page",
+        "summary": "List Jobs Paginated",
         "description": "List of jobs on a specific released solver (includes pagination)\n\nNew in *version 0.7*",
-        "operationId": "get_jobs_page",
+        "operationId": "list_jobs_paginated",
         "security": [
           {
             "HTTPBasic": []
@@ -3777,7 +3779,7 @@
           "solvers"
         ],
         "summary": "Get Job Output Logfile",
-        "description": "Special extra output with persistent logs file for the solver run.\n\n**NOTE**: this is not a log stream but a predefined output that is only\navailable after the job is done.\n\nNew in *version 0.4.0*",
+        "description": "Special extra output with persistent logs file for the solver run.\n\n**NOTE**: this is not a log stream but a predefined output that is only\navailable after the job is done\n\nNew in *version 0.4*",
         "operationId": "get_job_output_logfile",
         "security": [
           {
@@ -4319,7 +4321,7 @@
           "studies"
         ],
         "summary": "List Studies",
-        "description": "New in *version 0.5.0*",
+        "description": "List all studies\n\nNew in *version 0.5*",
         "operationId": "list_studies",
         "security": [
           {
@@ -4381,7 +4383,7 @@
           "studies"
         ],
         "summary": "Get Study",
-        "description": "New in *version 0.5.0*",
+        "description": "Get study by ID\n\nNew in *version 0.5*",
         "operationId": "get_study",
         "security": [
           {
@@ -4532,7 +4534,7 @@
           "studies"
         ],
         "summary": "List Study Ports",
-        "description": "Lists metadata on ports of a given study\n\nNew in *version 0.5.0*",
+        "description": "Lists metadata on ports of a given study\n\nNew in *version 0.5*",
         "operationId": "list_study_ports",
         "security": [
           {
@@ -4756,7 +4758,7 @@
           "studies"
         ],
         "summary": "Start Study Job",
-        "description": "Changed in *version 0.6.0*: Now responds with a 202 when successfully starting a computation\nChanged in *version 0.8*: query parameter `cluster_id` deprecated",
+        "description": "Changed in *version 0.6*: Now responds with a 202 when successfully starting a computation",
         "operationId": "start_study_job",
         "security": [
           {
@@ -4798,9 +4800,11 @@
                   "type": "null"
                 }
               ],
+              "description": "Changed in *version 0.7*: query parameter `cluster_id` deprecated\n",
               "deprecated": true,
               "title": "Cluster Id"
             },
+            "description": "Changed in *version 0.7*: query parameter `cluster_id` deprecated\n",
             "deprecated": true
           }
         ],
@@ -6217,7 +6221,7 @@
           "wallets"
         ],
         "summary": "Get Available Licensed Items For Wallet",
-        "description": "Get all available licensed items for a given wallet",
+        "description": "Get all available licensed items for a given wallet\n\nNew in *version 0.6*",
         "operationId": "get_available_licensed_items_for_wallet",
         "security": [
           {
@@ -6496,7 +6500,7 @@
           "credits"
         ],
         "summary": "Get Credits Price",
-        "description": "New in *version 0.6.0*",
+        "description": "New in *version 0.6*",
         "operationId": "get_credits_price",
         "responses": {
           "200": {

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

@@ -37,10 +37,10 @@ def create_route_description(
     changelog: list[str] | None = None
 ) -> str:
     """
-    Builds a consistent route description with optional deprecation and changelog information.
+    Builds a consistent route/query description with optional deprecation and changelog information.
 
     Args:
-        base (str): Main route description.
+        base (str): Main route/query description.
         deprecated (tuple): (retirement_date, alternative_route) if deprecated.
         changelog (List[str]): List of formatted changelog strings.
 

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

@@ -4,7 +4,7 @@
 
 from ...models.schemas.model_adapter import GetCreditPriceLegacy
 from ..dependencies.webserver_http import AuthSession, get_webserver_session
-from ._constants import FMSG_CHANGELOG_NEW_IN_VERSION
+from ._constants import FMSG_CHANGELOG_NEW_IN_VERSION, create_route_description
 
 router = APIRouter()
 
@@ -13,7 +13,11 @@
     "/price",
     status_code=status.HTTP_200_OK,
     response_model=GetCreditPriceLegacy,
-    description=FMSG_CHANGELOG_NEW_IN_VERSION.format("0.6.0"),
+    description=create_route_description(
+        changelog=[
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.6"),
+        ]
+    ),
 )
 async def get_credits_price(
     webserver_api: Annotated[AuthSession, Depends(get_webserver_session)],

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

@@ -57,7 +57,7 @@
         deprecated=True,
         alternative="GET /v0/solvers/page",
         changelog=[
-            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0", ""),
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
         ],
     ),
 )
@@ -84,12 +84,12 @@ async def list_solvers(
     description=create_route_description(
         base="Lists the latest version of all available solvers (paginated)",
         changelog=[
-            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.8"),
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.9-rc1"),
         ],
     ),
-    include_in_schema=False,  # TO BE RELEASED in 0.8
+    include_in_schema=False,  # TO BE RELEASED in 0.9
 )
-async def get_solvers_page(
+async def list_solvers_paginated(
     page_params: Annotated[PaginationParams, Depends()],
     solver_service: Annotated[SolverService, Depends(get_solver_service)],
     filters: Annotated[SolversListFilters, Depends(get_solvers_filters)],
@@ -118,11 +118,11 @@ async def get_solvers_page(
     summary="Lists All Releases",
     responses=_SOLVER_STATUS_CODES,
     description=create_route_description(
-        base="Lists all released solvers (not just latest version)",
+        base="Lists **all** released solvers (not just latest version)",
         deprecated=True,
         alternative="GET /v0/solvers/{solver_key}/releases/page",
         changelog=[
-            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0", ""),
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
         ],
     ),
 )
@@ -236,12 +236,12 @@ async def list_solver_releases(
     description=create_route_description(
         base="Lists all releases of a give solver (paginated)",
         changelog=[
-            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.8"),
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.9-rc1"),
         ],
     ),
-    include_in_schema=False,  # TO BE RELEASED in 0.8
+    include_in_schema=False,  # TO BE RELEASED in 0.9
 )
-async def get_solver_releases_page(
+async def list_solver_releases_paginated(
     solver_key: SolverKeyId,
     page_params: Annotated[PaginationParams, Depends()],
     url_for: Annotated[Callable, Depends(get_reverse_url_mapper)],
@@ -315,7 +315,7 @@ async def get_solver_release(
     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_NEW_IN_VERSION.format("0.5"),
             FMSG_CHANGELOG_ADDED_IN_VERSION.format(
                 "0.7.1", "`version_display` field in the response"
             ),

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

@@ -40,6 +40,7 @@
     FMSG_CHANGELOG_ADDED_IN_VERSION,
     FMSG_CHANGELOG_CHANGED_IN_VERSION,
     FMSG_CHANGELOG_NEW_IN_VERSION,
+    create_route_description,
 )
 
 _logger = logging.getLogger(__name__)
@@ -85,6 +86,12 @@ def compose_job_resource_name(solver_key, solver_version, job_id) -> str:
     response_model=Job,
     status_code=status.HTTP_201_CREATED,
     responses=JOBS_STATUS_CODES,
+    description=create_route_description(
+        base="Creates a job in a specific release with given inputs. This operation does not start the job.",
+        changelog=[
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
+        ],
+    ),
 )
 async def create_solver_job(  # noqa: PLR0913
     solver_key: SolverKeyId,
@@ -125,8 +132,12 @@ async def create_solver_job(  # noqa: PLR0913
     "/{solver_key:path}/releases/{version}/jobs/{job_id:uuid}",
     status_code=status.HTTP_204_NO_CONTENT,
     responses=JOBS_STATUS_CODES,
-    description="Deletes an existing solver job\n\n"
-    + FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
+    description=create_route_description(
+        base="Deletes an existing solver job",
+        changelog=[
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
+        ],
+    ),
 )
 async def delete_job(
     solver_key: SolverKeyId,
@@ -159,13 +170,19 @@ async def delete_job(
             "model": ErrorGet,
         },
     },
-    description="Starts job job_id created with the solver solver_key:version\n\n"
-    + FMSG_CHANGELOG_ADDED_IN_VERSION.format("0.4.3", "query parameter `cluster_id`")
-    + FMSG_CHANGELOG_ADDED_IN_VERSION.format(
-        "0.6", "responds with a 202 when successfully starting a computation"
-    )
-    + FMSG_CHANGELOG_CHANGED_IN_VERSION.format(
-        "0.8", "query parameter `cluster_id` deprecated"
+    description=create_route_description(
+        base="Starts job job_id created with the solver solver_key:version",
+        changelog=[
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.4.3", "query parameter `cluster_id`"
+            ),
+            FMSG_CHANGELOG_ADDED_IN_VERSION.format(
+                "0.6", "responds with a 202 when successfully starting a computation"
+            ),
+            FMSG_CHANGELOG_CHANGED_IN_VERSION.format(
+                "0.7", "query parameter `cluster_id` deprecated"
+            ),
+        ],
     ),
 )
 async def start_job(
@@ -214,6 +231,12 @@ async def start_job(
     "/{solver_key:path}/releases/{version}/jobs/{job_id:uuid}:stop",
     response_model=JobStatus,
     responses=JOBS_STATUS_CODES,
+    description=create_route_description(
+        base="Stops a running job",
+        changelog=[
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
+        ],
+    ),
 )
 async def stop_job(
     solver_key: SolverKeyId,
@@ -234,6 +257,12 @@ async def stop_job(
     "/{solver_key:path}/releases/{version}/jobs/{job_id:uuid}:inspect",
     response_model=JobStatus,
     responses=JOBS_STATUS_CODES,
+    description=create_route_description(
+        base="Inspects the current status of a job",
+        changelog=[
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
+        ],
+    ),
 )
 async def inspect_job(
     solver_key: SolverKeyId,
@@ -254,8 +283,12 @@ async def inspect_job(
     "/{solver_key:path}/releases/{version}/jobs/{job_id:uuid}/metadata",
     response_model=JobMetadata,
     responses=METADATA_STATUS_CODES,
-    description="Updates custom metadata from a job\n\n"
-    + FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
+    description=create_route_description(
+        base="Updates custom metadata from a job",
+        changelog=[
+            FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
+        ],
+    ),
 )
 async def replace_job_custom_metadata(
     solver_key: SolverKeyId,