From 89da5d9d014bd3e5b3b3662e61aa871c1350b89e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Laura=20Kl=C3=BCnder?= Date: Sun, 3 Dec 2023 19:43:38 +0100 Subject: [PATCH] improve api v2 documentation for routing --- src/c3nav/routing/newapi/routing.py | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/c3nav/routing/newapi/routing.py b/src/c3nav/routing/newapi/routing.py index fa5a8b0c..a4b703e6 100644 --- a/src/c3nav/routing/newapi/routing.py +++ b/src/c3nav/routing/newapi/routing.py @@ -110,7 +110,8 @@ def get_request_pk(location): return location.slug if isinstance(location, Position) else location.pk -@routing_api_router.post('/route/', summary="get route between two locations", +@routing_api_router.post('/route/', summary="query route", + description="query route between two locations", response={200: RouteResponse | NoRouteResponse, **validate_responses, **auth_responses}) # todo: route failure responses def get_route(request, parameters: RouteParametersSchema): @@ -198,14 +199,17 @@ def _new_update_route_options(options, new_options): raise APIRequestValidationFailed(str(e)) -@routing_api_router.get('/options/', summary="get current route options", +@routing_api_router.get('/options/', summary="current route options", + description="get current preferred route options for this user (or session, if signed out)", response={200: RouteOptionsSchema, **auth_responses}) def get_route_options(request): + # todo: API key should not override for user options = RouteOptions.get_for_request(request) return _new_serialize_route_options(options) -@routing_api_router.put('/options/', summary="set route options for user or session", +@routing_api_router.put('/options/', summary="set route options", + description="set current preferred route options for this user (or session, if signed out)", response={200: RouteOptionsSchema, **validate_responses, **auth_responses}) def set_route_options(request, new_options: RouteOptionsSchema): options = RouteOptions.get_for_request(request) @@ -216,8 +220,6 @@ def set_route_options(request, new_options: RouteOptionsSchema): return _new_serialize_route_options(options) - - class RouteOptionsFieldChoices(Schema): name: NonEmptyStr title: NonEmptyStr @@ -232,7 +234,8 @@ class RouteOptionsField(Schema): value_display: NonEmptyStr -@routing_api_router.get('/options/form/', summary="get current route options with form definitions (like old API)", +@routing_api_router.get('/options/form/', summary="get route options form", + description="get description of all form options, to render like a form (like old API)", response={200: list[RouteOptionsField], **auth_responses}) def get_route_options_form(request): options = RouteOptions.get_for_request(request)