Skip to content

Commit 86a2063

Browse files
pcrespovpcrespov
committed
updates oas description
1 parent c591a6f commit 86a2063

File tree

9 files changed

+163
-72
lines changed

9 files changed

+163
-72
lines changed

‎services/api-server/openapi.json‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1423,7 +1423,7 @@
14231423
"solvers"
14241424
],
14251425
"summary": "List Solvers",
1426-
"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*",
1426+
"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*",
14271427
"operationId": "list_solvers",
14281428
"responses": {
14291429
"200": {
@@ -1514,7 +1514,7 @@
15141514
"solvers"
15151515
],
15161516
"summary": "Lists All Releases",
1517-
"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*",
1517+
"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*",
15181518
"operationId": "list_solvers_releases",
15191519
"responses": {
15201520
"200": {
@@ -1599,7 +1599,7 @@
15991599
]
16001600
}
16011601
},
1602-
"/v0/solvers/{solver_key}/latest": {
1602+
"/v0/solvers/{solver_key}/releases/latest": {
16031603
"get": {
16041604
"tags": [
16051605
"solvers"
@@ -1946,7 +1946,7 @@
19461946
"solvers"
19471947
],
19481948
"summary": "List Solver Ports",
1949-
"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",
1949+
"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",
19501950
"operationId": "list_solver_ports",
19511951
"security": [
19521952
{
@@ -2184,7 +2184,7 @@
21842184
"solvers"
21852185
],
21862186
"summary": "Create Solver Job",
2187-
"description": "Creates a job in a specific release with given inputs.\n\nNOTE: This operation does **not** start the job",
2187+
"description": "Creates a job in a specific release with given inputs. This operation does not start the job.\n\nNew in *version 0.5*",
21882188
"operationId": "create_solver_job",
21892189
"security": [
21902190
{
@@ -2767,7 +2767,7 @@
27672767
"solvers"
27682768
],
27692769
"summary": "Start Job",
2770-
"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",
2770+
"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",
27712771
"operationId": "start_job",
27722772
"security": [
27732773
{
@@ -2945,6 +2945,7 @@
29452945
"solvers"
29462946
],
29472947
"summary": "Stop Job",
2948+
"description": "Stops a running job\n\nNew in *version 0.5*",
29482949
"operationId": "stop_job",
29492950
"security": [
29502951
{
@@ -3083,6 +3084,7 @@
30833084
"solvers"
30843085
],
30853086
"summary": "Inspect Job",
3087+
"description": "Inspects the current status of a job\n\nNew in *version 0.5*",
30863088
"operationId": "inspect_job",
30873089
"security": [
30883090
{
@@ -3777,7 +3779,7 @@
37773779
"solvers"
37783780
],
37793781
"summary": "Get Job Output Logfile",
3780-
"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*",
3782+
"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*",
37813783
"operationId": "get_job_output_logfile",
37823784
"security": [
37833785
{
@@ -4319,7 +4321,7 @@
43194321
"studies"
43204322
],
43214323
"summary": "List Studies",
4322-
"description": "New in *version 0.5.0*",
4324+
"description": "List all studies\n\nNew in *version 0.5*",
43234325
"operationId": "list_studies",
43244326
"security": [
43254327
{
@@ -4381,7 +4383,7 @@
43814383
"studies"
43824384
],
43834385
"summary": "Get Study",
4384-
"description": "New in *version 0.5.0*",
4386+
"description": "Get study by ID\n\nNew in *version 0.5*",
43854387
"operationId": "get_study",
43864388
"security": [
43874389
{
@@ -4532,7 +4534,7 @@
45324534
"studies"
45334535
],
45344536
"summary": "List Study Ports",
4535-
"description": "Lists metadata on ports of a given study\n\nNew in *version 0.5.0*",
4537+
"description": "Lists metadata on ports of a given study\n\nNew in *version 0.5*",
45364538
"operationId": "list_study_ports",
45374539
"security": [
45384540
{
@@ -4756,7 +4758,7 @@
47564758
"studies"
47574759
],
47584760
"summary": "Start Study Job",
4759-
"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",
4761+
"description": "Changed in *version 0.6*: Now responds with a 202 when successfully starting a computation",
47604762
"operationId": "start_study_job",
47614763
"security": [
47624764
{
@@ -4798,9 +4800,11 @@
47984800
"type": "null"
47994801
}
48004802
],
4803+
"description": "Changed in *version 0.7*: query parameter `cluster_id` deprecated\n",
48014804
"deprecated": true,
48024805
"title": "Cluster Id"
48034806
},
4807+
"description": "Changed in *version 0.7*: query parameter `cluster_id` deprecated\n",
48044808
"deprecated": true
48054809
}
48064810
],
@@ -6217,7 +6221,7 @@
62176221
"wallets"
62186222
],
62196223
"summary": "Get Available Licensed Items For Wallet",
6220-
"description": "Get all available licensed items for a given wallet",
6224+
"description": "Get all available licensed items for a given wallet\n\nNew in *version 0.6*",
62216225
"operationId": "get_available_licensed_items_for_wallet",
62226226
"security": [
62236227
{
@@ -6496,7 +6500,7 @@
64966500
"credits"
64976501
],
64986502
"summary": "Get Credits Price",
6499-
"description": "New in *version 0.6.0*",
6503+
"description": "New in *version 0.6*",
65006504
"operationId": "get_credits_price",
65016505
"responses": {
65026506
"200": {

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,10 @@ def create_route_description(
3737
changelog: list[str] | None = None
3838
) -> str:
3939
"""
40-
Builds a consistent route description with optional deprecation and changelog information.
40+
Builds a consistent route/query description with optional deprecation and changelog information.
4141
4242
Args:
43-
base (str): Main route description.
43+
base (str): Main route/query description.
4444
deprecated (tuple): (retirement_date, alternative_route) if deprecated.
4545
changelog (List[str]): List of formatted changelog strings.
4646

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

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
from ...models.schemas.model_adapter import GetCreditPriceLegacy
66
from ..dependencies.webserver_http import AuthSession, get_webserver_session
7-
from ._constants import FMSG_CHANGELOG_NEW_IN_VERSION
7+
from ._constants import FMSG_CHANGELOG_NEW_IN_VERSION, create_route_description
88

99
router = APIRouter()
1010

@@ -13,7 +13,11 @@
1313
"/price",
1414
status_code=status.HTTP_200_OK,
1515
response_model=GetCreditPriceLegacy,
16-
description=FMSG_CHANGELOG_NEW_IN_VERSION.format("0.6.0"),
16+
description=create_route_description(
17+
changelog=[
18+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.6"),
19+
]
20+
),
1721
)
1822
async def get_credits_price(
1923
webserver_api: Annotated[AuthSession, Depends(get_webserver_session)],

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

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@
5757
deprecated=True,
5858
alternative="GET /v0/solvers/page",
5959
changelog=[
60-
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0", ""),
60+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
6161
],
6262
),
6363
)
@@ -84,12 +84,12 @@ async def list_solvers(
8484
description=create_route_description(
8585
base="Lists the latest version of all available solvers (paginated)",
8686
changelog=[
87-
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.8"),
87+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.9-rc1"),
8888
],
8989
),
90-
include_in_schema=False, # TO BE RELEASED in 0.8
90+
include_in_schema=False, # TO BE RELEASED in 0.9
9191
)
92-
async def get_solvers_page(
92+
async def list_solvers_paginated(
9393
page_params: Annotated[PaginationParams, Depends()],
9494
solver_service: Annotated[SolverService, Depends(get_solver_service)],
9595
filters: Annotated[SolversListFilters, Depends(get_solvers_filters)],
@@ -118,11 +118,11 @@ async def get_solvers_page(
118118
summary="Lists All Releases",
119119
responses=_SOLVER_STATUS_CODES,
120120
description=create_route_description(
121-
base="Lists all released solvers (not just latest version)",
121+
base="Lists **all** released solvers (not just latest version)",
122122
deprecated=True,
123123
alternative="GET /v0/solvers/{solver_key}/releases/page",
124124
changelog=[
125-
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0", ""),
125+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
126126
],
127127
),
128128
)
@@ -160,7 +160,7 @@ async def list_solvers_releases(
160160

161161

162162
@router.get(
163-
"/{solver_key:path}/latest",
163+
"/{solver_key:path}/releases/latest",
164164
response_model=Solver,
165165
responses=_SOLVER_STATUS_CODES,
166166
description=create_route_description(
@@ -236,12 +236,12 @@ async def list_solver_releases(
236236
description=create_route_description(
237237
base="Lists all releases of a give solver (paginated)",
238238
changelog=[
239-
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.8"),
239+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.9-rc1"),
240240
],
241241
),
242-
include_in_schema=False, # TO BE RELEASED in 0.8
242+
include_in_schema=False, # TO BE RELEASED in 0.9
243243
)
244-
async def get_solver_releases_page(
244+
async def list_solver_releases_page(
245245
solver_key: SolverKeyId,
246246
page_params: Annotated[PaginationParams, Depends()],
247247
url_for: Annotated[Callable, Depends(get_reverse_url_mapper)],
@@ -315,7 +315,7 @@ async def get_solver_release(
315315
description=create_route_description(
316316
base="Lists inputs and outputs of a given solver",
317317
changelog=[
318-
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5.0"),
318+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
319319
FMSG_CHANGELOG_ADDED_IN_VERSION.format(
320320
"0.7.1", "`version_display` field in the response"
321321
),

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

Lines changed: 44 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
FMSG_CHANGELOG_ADDED_IN_VERSION,
4141
FMSG_CHANGELOG_CHANGED_IN_VERSION,
4242
FMSG_CHANGELOG_NEW_IN_VERSION,
43+
create_route_description,
4344
)
4445

4546
_logger = logging.getLogger(__name__)
@@ -85,6 +86,12 @@ def compose_job_resource_name(solver_key, solver_version, job_id) -> str:
8586
response_model=Job,
8687
status_code=status.HTTP_201_CREATED,
8788
responses=JOBS_STATUS_CODES,
89+
description=create_route_description(
90+
base="Creates a job in a specific release with given inputs. This operation does not start the job.",
91+
changelog=[
92+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
93+
],
94+
),
8895
)
8996
async def create_solver_job( # noqa: PLR0913
9097
solver_key: SolverKeyId,
@@ -125,8 +132,12 @@ async def create_solver_job( # noqa: PLR0913
125132
"/{solver_key:path}/releases/{version}/jobs/{job_id:uuid}",
126133
status_code=status.HTTP_204_NO_CONTENT,
127134
responses=JOBS_STATUS_CODES,
128-
description="Deletes an existing solver job\n\n"
129-
+ FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
135+
description=create_route_description(
136+
base="Deletes an existing solver job",
137+
changelog=[
138+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
139+
],
140+
),
130141
)
131142
async def delete_job(
132143
solver_key: SolverKeyId,
@@ -159,13 +170,19 @@ async def delete_job(
159170
"model": ErrorGet,
160171
},
161172
},
162-
description="Starts job job_id created with the solver solver_key:version\n\n"
163-
+ FMSG_CHANGELOG_ADDED_IN_VERSION.format("0.4.3", "query parameter `cluster_id`")
164-
+ FMSG_CHANGELOG_ADDED_IN_VERSION.format(
165-
"0.6", "responds with a 202 when successfully starting a computation"
166-
)
167-
+ FMSG_CHANGELOG_CHANGED_IN_VERSION.format(
168-
"0.8", "query parameter `cluster_id` deprecated"
173+
description=create_route_description(
174+
base="Starts job job_id created with the solver solver_key:version",
175+
changelog=[
176+
FMSG_CHANGELOG_ADDED_IN_VERSION.format(
177+
"0.4.3", "query parameter `cluster_id`"
178+
),
179+
FMSG_CHANGELOG_ADDED_IN_VERSION.format(
180+
"0.6", "responds with a 202 when successfully starting a computation"
181+
),
182+
FMSG_CHANGELOG_CHANGED_IN_VERSION.format(
183+
"0.7", "query parameter `cluster_id` deprecated"
184+
),
185+
],
169186
),
170187
)
171188
async def start_job(
@@ -214,6 +231,12 @@ async def start_job(
214231
"/{solver_key:path}/releases/{version}/jobs/{job_id:uuid}:stop",
215232
response_model=JobStatus,
216233
responses=JOBS_STATUS_CODES,
234+
description=create_route_description(
235+
base="Stops a running job",
236+
changelog=[
237+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
238+
],
239+
),
217240
)
218241
async def stop_job(
219242
solver_key: SolverKeyId,
@@ -234,6 +257,12 @@ async def stop_job(
234257
"/{solver_key:path}/releases/{version}/jobs/{job_id:uuid}:inspect",
235258
response_model=JobStatus,
236259
responses=JOBS_STATUS_CODES,
260+
description=create_route_description(
261+
base="Inspects the current status of a job",
262+
changelog=[
263+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.5"),
264+
],
265+
),
237266
)
238267
async def inspect_job(
239268
solver_key: SolverKeyId,
@@ -254,8 +283,12 @@ async def inspect_job(
254283
"/{solver_key:path}/releases/{version}/jobs/{job_id:uuid}/metadata",
255284
response_model=JobMetadata,
256285
responses=METADATA_STATUS_CODES,
257-
description="Updates custom metadata from a job\n\n"
258-
+ FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
286+
description=create_route_description(
287+
base="Updates custom metadata from a job",
288+
changelog=[
289+
FMSG_CHANGELOG_NEW_IN_VERSION.format("0.7"),
290+
],
291+
),
259292
)
260293
async def replace_job_custom_metadata(
261294
solver_key: SolverKeyId,

0 commit comments

Comments
 (0)