From 65272042f931466f4e5b2ba0c11354d6e9f76031 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Laura=20Kl=C3=BCnder?= Date: Sun, 3 Dec 2023 20:12:27 +0100 Subject: [PATCH] improve mapdata api v2 docs --- src/c3nav/mapdata/newapi/mapdata.py | 200 +++++++++++----------------- 1 file changed, 80 insertions(+), 120 deletions(-) diff --git a/src/c3nav/mapdata/newapi/mapdata.py b/src/c3nav/mapdata/newapi/mapdata.py index 220fed0f..0e4be7e6 100644 --- a/src/c3nav/mapdata/newapi/mapdata.py +++ b/src/c3nav/mapdata/newapi/mapdata.py @@ -68,17 +68,15 @@ class LevelFilters(ByGroupFilter, ByOnTopOfFilter): pass -@mapdata_api_router.get('/levels/', - response={200: list[LevelSchema], **validate_responses, **auth_responses}, - summary="Get level list") +@mapdata_api_router.get('/levels/', summary="level list", + response={200: list[LevelSchema], **validate_responses, **auth_responses}) @newapi_etag() def level_list(request, filters: Query[LevelFilters]): return mapdata_list_endpoint(request, model=Level, filters=filters) -@mapdata_api_router.get('/levels/{level_id}/', - response={200: LevelSchema, **API404.dict(), **auth_responses}, - summary="Get level by ID") +@mapdata_api_router.get('/levels/{level_id}/', summary="level by ID", + response={200: LevelSchema, **API404.dict(), **auth_responses}) @newapi_etag() def level_by_id(request, level_id: int): return mapdata_retrieve_endpoint(request, Level, pk=level_id) @@ -89,17 +87,15 @@ Buildings """ -@mapdata_api_router.get('/buildings/', - response={200: list[BuildingSchema], **validate_responses, **auth_responses}, - summary="Get building list") +@mapdata_api_router.get('/buildings/', summary="building list", + response={200: list[BuildingSchema], **validate_responses, **auth_responses}) @newapi_etag(base_mapdata=True) def building_list(request, filters: Query[LevelGeometryFilter]): return mapdata_list_endpoint(request, model=Building, filters=filters) -@mapdata_api_router.get('/buildings/{building_id}/', - response={200: BuildingSchema, **API404.dict(), **auth_responses}, - summary="Get building by ID") +@mapdata_api_router.get('/buildings/{building_id}/', summary="building by ID", + response={200: BuildingSchema, **API404.dict(), **auth_responses}) @newapi_etag(base_mapdata=True) def building_by_id(request, building_id: int): return mapdata_retrieve_endpoint(request, Building, pk=building_id) @@ -114,17 +110,15 @@ class SpaceFilters(ByGroupFilter, LevelGeometryFilter): pass -@mapdata_api_router.get('/spaces/', - response={200: list[SpaceSchema], **validate_responses, **auth_responses}, - summary="Get space list") +@mapdata_api_router.get('/spaces/', summary="space list", + response={200: list[SpaceSchema], **validate_responses, **auth_responses}) @newapi_etag(base_mapdata=True) def space_list(request, filters: Query[SpaceFilters]): return mapdata_list_endpoint(request, model=Space, filters=filters) -@mapdata_api_router.get('/space/{space_id}/', - response={200: SpaceSchema, **API404.dict(), **auth_responses}, - summary="Get space by ID") +@mapdata_api_router.get('/space/{space_id}/', summary="space by ID", + response={200: SpaceSchema, **API404.dict(), **auth_responses}) @newapi_etag(base_mapdata=True) def space_by_id(request, space_id: int): return mapdata_retrieve_endpoint(request, Space, pk=space_id) @@ -135,17 +129,15 @@ Doors """ -@mapdata_api_router.get('/doors/', - response={200: list[DoorSchema], **validate_responses, **auth_responses}, - summary="Get door list") +@mapdata_api_router.get('/doors/', summary="door list", + response={200: list[DoorSchema], **validate_responses, **auth_responses}) @newapi_etag(base_mapdata=True) def door_list(request, filters: Query[LevelGeometryFilter]): return mapdata_list_endpoint(request, model=Door, filters=filters) -@mapdata_api_router.get('/doors/{door_id}/', - response={200: DoorSchema, **API404.dict(), **auth_responses}, - summary="Get door by ID") +@mapdata_api_router.get('/doors/{door_id}/', summary="door by ID", + response={200: DoorSchema, **API404.dict(), **auth_responses}) @newapi_etag(base_mapdata=True) def door_by_id(request, door_id: int): return mapdata_retrieve_endpoint(request, Door, pk=door_id) @@ -156,17 +148,15 @@ Holes """ -@mapdata_api_router.get('/holes/', - response={200: list[HoleSchema], **validate_responses, **auth_responses}, - summary="Get hole list") +@mapdata_api_router.get('/holes/', summary="hole list", + response={200: list[HoleSchema], **validate_responses, **auth_responses}) @newapi_etag() def hole_list(request, filters: Query[SpaceGeometryFilter]): return mapdata_list_endpoint(request, model=Hole, filters=filters) -@mapdata_api_router.get('/holes/{hole_id}/', - response={200: HoleSchema, **API404.dict(), **auth_responses}, - summary="Get hole by ID") +@mapdata_api_router.get('/holes/{hole_id}/', summary="hole by id", + response={200: HoleSchema, **API404.dict(), **auth_responses}) @newapi_etag() def hole_by_id(request, hole_id: int): return mapdata_retrieve_endpoint(request, Hole, pk=hole_id) @@ -181,17 +171,15 @@ class AreaFilters(ByGroupFilter, SpaceGeometryFilter): pass -@mapdata_api_router.get('/areas/', - response={200: list[AreaSchema], **validate_responses, **auth_responses}, - summary="Get area list") +@mapdata_api_router.get('/areas/', summary="area list", + response={200: list[AreaSchema], **validate_responses, **auth_responses}) @newapi_etag() def area_list(request, filters: Query[AreaFilters]): return mapdata_list_endpoint(request, model=Area, filters=filters) -@mapdata_api_router.get('/areas/{area_id}/', - response={200: AreaSchema, **API404.dict(), **auth_responses}, - summary="Get area by ID") +@mapdata_api_router.get('/areas/{area_id}/', summary="area by ID", + response={200: AreaSchema, **API404.dict(), **auth_responses}) @newapi_etag() def area_by_id(request, area_id: int): return mapdata_retrieve_endpoint(request, Area, pk=area_id) @@ -202,17 +190,15 @@ Stairs """ -@mapdata_api_router.get('/stairs/', - response={200: list[StairSchema], **validate_responses, **auth_responses}, - summary="Get stair list") +@mapdata_api_router.get('/stairs/', summary="stair list", + response={200: list[StairSchema], **validate_responses, **auth_responses}) @newapi_etag() def stair_list(request, filters: Query[SpaceGeometryFilter]): return mapdata_list_endpoint(request, model=Stair, filters=filters) -@mapdata_api_router.get('/stairs/{stair_id}/', - response={200: StairSchema, **API404.dict(), **auth_responses}, - summary="Get stair by ID") +@mapdata_api_router.get('/stairs/{stair_id}/', summary="stair by ID", + response={200: StairSchema, **API404.dict(), **auth_responses}) @newapi_etag() def stair_by_id(request, stair_id: int): return mapdata_retrieve_endpoint(request, Stair, pk=stair_id) @@ -223,17 +209,15 @@ Ramps """ -@mapdata_api_router.get('/ramps/', - response={200: list[RampSchema], **validate_responses, **auth_responses}, - summary="Get ramp list") +@mapdata_api_router.get('/ramps/', summary="ramp list", + response={200: list[RampSchema], **validate_responses, **auth_responses}) @newapi_etag() def ramp_list(request, filters: Query[SpaceGeometryFilter]): return mapdata_list_endpoint(request, model=Ramp, filters=filters) -@mapdata_api_router.get('/ramps/{ramp_id}/', - response={200: RampSchema, **API404.dict(), **auth_responses}, - summary="Get ramp by ID") +@mapdata_api_router.get('/ramps/{ramp_id}/', summary="ramp by ID", + response={200: RampSchema, **API404.dict(), **auth_responses}) @newapi_etag() def ramp_by_id(request, ramp_id: int): return mapdata_retrieve_endpoint(request, Ramp, pk=ramp_id) @@ -244,17 +228,15 @@ Obstacles """ -@mapdata_api_router.get('/obstacles/', - response={200: list[ObstacleSchema], **validate_responses, **auth_responses}, - summary="Get obstacle list") +@mapdata_api_router.get('/obstacles/', summary="obstacle list", + response={200: list[ObstacleSchema], **validate_responses, **auth_responses}) @newapi_etag() def obstacle_list(request, filters: Query[SpaceGeometryFilter]): return mapdata_list_endpoint(request, model=Obstacle, filters=filters) -@mapdata_api_router.get('/obstacles/{obstacle_id}/', - response={200: ObstacleSchema, **API404.dict(), **auth_responses}, - summary="Get obstacle by ID") +@mapdata_api_router.get('/obstacles/{obstacle_id}/', summary="obstacle by ID", + response={200: ObstacleSchema, **API404.dict(), **auth_responses}) @newapi_etag() def obstacle_by_id(request, obstacle_id: int): return mapdata_retrieve_endpoint(request, Obstacle, pk=obstacle_id) @@ -265,17 +247,15 @@ LineObstacles """ -@mapdata_api_router.get('/lineobstacles/', - response={200: list[LineObstacleSchema], **validate_responses, **auth_responses}, - summary="Get line obstacle list") +@mapdata_api_router.get('/lineobstacles/', summary="line obstacle list", + response={200: list[LineObstacleSchema], **validate_responses, **auth_responses}) @newapi_etag() def lineobstacle_list(request, filters: Query[SpaceGeometryFilter]): return mapdata_list_endpoint(request, model=LineObstacle, filters=filters) -@mapdata_api_router.get('/lineobstacles/{lineobstacle_id}/', - response={200: LineObstacleSchema, **API404.dict(), **auth_responses}, - summary="Get line obstacle by ID") +@mapdata_api_router.get('/lineobstacles/{lineobstacle_id}/', summary="line obstacle by ID", + response={200: LineObstacleSchema, **API404.dict(), **auth_responses},) @newapi_etag() def lineobstacle_by_id(request, lineobstacle_id: int): return mapdata_retrieve_endpoint(request, LineObstacle, pk=lineobstacle_id) @@ -286,17 +266,15 @@ Columns """ -@mapdata_api_router.get('/columns/', - response={200: list[ColumnSchema], **validate_responses, **auth_responses}, - summary="Get column list") +@mapdata_api_router.get('/columns/', summary="column list", + response={200: list[ColumnSchema], **validate_responses, **auth_responses}) @newapi_etag() def column_list(request, filters: Query[SpaceGeometryFilter]): return mapdata_list_endpoint(request, model=Column, filters=filters) -@mapdata_api_router.get('/columns/{column_id}/', - response={200: ColumnSchema, **API404.dict(), **auth_responses}, - summary="Get column by ID") +@mapdata_api_router.get('/columns/{column_id}/', summary="column by ID", + response={200: ColumnSchema, **API404.dict(), **auth_responses}) @newapi_etag() def column_by_id(request, column_id: int): return mapdata_retrieve_endpoint(request, Column, pk=column_id) @@ -307,17 +285,15 @@ POIs """ -@mapdata_api_router.get('/pois/', - response={200: list[POISchema], **validate_responses, **auth_responses}, - summary="Get POI list") +@mapdata_api_router.get('/pois/', summary="POI list", + response={200: list[POISchema], **validate_responses, **auth_responses}) @newapi_etag() def poi_list(request, filters: Query[SpaceGeometryFilter]): return mapdata_list_endpoint(request, model=POI, filters=filters) -@mapdata_api_router.get('/pois/{poi_id}/', - response={200: POISchema, **API404.dict(), **auth_responses}, - summary="Get POI by ID") +@mapdata_api_router.get('/pois/{poi_id}/', summary="POI by ID", + response={200: POISchema, **API404.dict(), **auth_responses}) @newapi_etag() def poi_by_id(request, poi_id: int): return mapdata_retrieve_endpoint(request, POI, pk=poi_id) @@ -328,17 +304,15 @@ LeaveDescriptions """ -@mapdata_api_router.get('/leavedescriptions/', - response={200: list[LeaveDescriptionSchema], **validate_responses, **auth_responses}, - summary="Get leave description list") +@mapdata_api_router.get('/leavedescriptions/', summary="leave description list", + response={200: list[LeaveDescriptionSchema], **validate_responses, **auth_responses}) @newapi_etag() def leavedescription_list(request, filters: Query[SpaceGeometryFilter]): return mapdata_list_endpoint(request, model=LeaveDescription, filters=filters) -@mapdata_api_router.get('/leavedescriptions/{leavedescription_id}/', - response={200: LeaveDescriptionSchema, **API404.dict(), **auth_responses}, - summary="Get leave description by ID") +@mapdata_api_router.get('/leavedescriptions/{leavedescription_id}/', summary="leave description by ID", + response={200: LeaveDescriptionSchema, **API404.dict(), **auth_responses}) @newapi_etag() def leavedescription_by_id(request, leavedescription_id: int): return mapdata_retrieve_endpoint(request, LeaveDescription, pk=leavedescription_id) @@ -349,17 +323,15 @@ CrossDescriptions """ -@mapdata_api_router.get('/crossdescriptions/', - response={200: list[CrossDescriptionSchema], **validate_responses, **auth_responses}, - summary="Get cross description list") +@mapdata_api_router.get('/crossdescriptions/', summary="cross description list", + response={200: list[CrossDescriptionSchema], **validate_responses, **auth_responses}) @newapi_etag() def crossdescription_list(request, filters: Query[SpaceGeometryFilter]): return mapdata_list_endpoint(request, model=CrossDescription, filters=filters) -@mapdata_api_router.get('/crossdescriptions/{crossdescription_id}/', - response={200: CrossDescriptionSchema, **API404.dict(), **auth_responses}, - summary="Get cross description by ID") +@mapdata_api_router.get('/crossdescriptions/{crossdescription_id}/', summary="cross description by ID", + response={200: CrossDescriptionSchema, **API404.dict(), **auth_responses}) @newapi_etag() def crossdescription_by_id(request, crossdescription_id: int): return mapdata_retrieve_endpoint(request, CrossDescription, pk=crossdescription_id) @@ -370,17 +342,15 @@ LocationGroup """ -@mapdata_api_router.get('/locationgroups/', - response={200: list[LocationGroupSchema], **validate_responses, **auth_responses}, - summary="Get location group list") +@mapdata_api_router.get('/locationgroups/', summary="location group list", + response={200: list[LocationGroupSchema], **validate_responses, **auth_responses}) @newapi_etag() def locationgroup_list(request, filters: Query[ByCategoryFilter]): return mapdata_list_endpoint(request, model=LocationGroup, filters=filters) -@mapdata_api_router.get('/locationgroups/{locationgroup_id}/', - response={200: LocationGroupSchema, **API404.dict(), **auth_responses}, - summary="Get location group by ID") +@mapdata_api_router.get('/locationgroups/{locationgroup_id}/', summary="location group by ID", + response={200: LocationGroupSchema, **API404.dict(), **auth_responses}) @newapi_etag() def locationgroup_by_id(request, locationgroup_id: int): return mapdata_retrieve_endpoint(request, LocationGroup, pk=locationgroup_id) @@ -391,17 +361,15 @@ LocationGroupCategories """ -@mapdata_api_router.get('/locationgroupcategories/', - response={200: list[LocationGroupCategorySchema], **auth_responses}, - summary="Get location group category list") +@mapdata_api_router.get('/locationgroupcategories/', summary="location group category list", + response={200: list[LocationGroupCategorySchema], **auth_responses}) @newapi_etag() def locationgroupcategory_list(request): return mapdata_list_endpoint(request, model=LocationGroupCategory) -@mapdata_api_router.get('/locationgroupcategories/{category_id}/', - response={200: LocationGroupCategorySchema, **API404.dict(), **auth_responses}, - summary="Get location group category by ID") +@mapdata_api_router.get('/locationgroupcategories/{category_id}/', summary="location group category by ID", + response={200: LocationGroupCategorySchema, **API404.dict(), **auth_responses}) @newapi_etag() def locationgroupcategory_by_id(request, category_id: int): return mapdata_retrieve_endpoint(request, LocationGroupCategory, pk=category_id) @@ -412,17 +380,15 @@ Sources """ -@mapdata_api_router.get('/sources/', - response={200: list[SourceSchema], **auth_responses}, - summary="Get source list") +@mapdata_api_router.get('/sources/', summary="source list", + response={200: list[SourceSchema], **auth_responses}) @newapi_etag() def source_list(request): return mapdata_list_endpoint(request, model=Source) -@mapdata_api_router.get('/sources/{source_id}/', - response={200: SourceSchema, **API404.dict(), **auth_responses}, - summary="Get source by ID") +@mapdata_api_router.get('/sources/{source_id}/', summary="source by ID", + response={200: SourceSchema, **API404.dict(), **auth_responses}) @newapi_etag() def source_by_id(request, source_id: int): return mapdata_retrieve_endpoint(request, Source, pk=source_id) @@ -433,17 +399,15 @@ AccessRestrictions """ -@mapdata_api_router.get('/accessrestrictions/', - response={200: list[AccessRestrictionSchema], **auth_responses}, - summary="Get access restriction list") +@mapdata_api_router.get('/accessrestrictions/', summary="access restriction list", + response={200: list[AccessRestrictionSchema], **auth_responses}) @newapi_etag() def accessrestriction_list(request): return mapdata_list_endpoint(request, model=AccessRestriction) -@mapdata_api_router.get('/accessrestrictions/{accessrestriction_id}/', - response={200: AccessRestrictionSchema, **API404.dict(), **auth_responses}, - summary="Get access restriction by ID") +@mapdata_api_router.get('/accessrestrictions/{accessrestriction_id}/', summary="access restriction by ID", + response={200: AccessRestrictionSchema, **API404.dict(), **auth_responses}) @newapi_etag() def accessrestriction_by_id(request, accessrestriction_id: int): return mapdata_retrieve_endpoint(request, AccessRestriction, pk=accessrestriction_id) @@ -454,17 +418,15 @@ AccessRestrictionGroups """ -@mapdata_api_router.get('/accessrestrictiongroups/', - response={200: list[AccessRestrictionGroupSchema], **auth_responses}, - summary="Get access restriction group list") +@mapdata_api_router.get('/accessrestrictiongroups/', summary="access restriction group list", + response={200: list[AccessRestrictionGroupSchema], **auth_responses}) @newapi_etag() def accessrestrictiongroup_list(request): return mapdata_list_endpoint(request, model=AccessRestrictionGroup) -@mapdata_api_router.get('/accessrestrictiongroups/{group_id}/', - response={200: AccessRestrictionGroupSchema, **API404.dict(), **auth_responses}, - summary="Get access restriction group by ID") +@mapdata_api_router.get('/accessrestrictiongroups/{group_id}/', summary="access restriction group by ID", + response={200: AccessRestrictionGroupSchema, **API404.dict(), **auth_responses}) @newapi_etag() def accessrestrictiongroups_by_id(request, group_id: int): return mapdata_retrieve_endpoint(request, AccessRestrictionGroup, pk=group_id) @@ -475,17 +437,15 @@ DynamicLocations """ -@mapdata_api_router.get('/dynamiclocations/', - response={200: list[DynamicLocationSchema], **auth_responses}, - summary="Get dynamic location list") +@mapdata_api_router.get('/dynamiclocations/', summary="dynamic location list", + response={200: list[DynamicLocationSchema], **auth_responses}) @newapi_etag() def dynamiclocation_list(request): return mapdata_list_endpoint(request, model=DynamicLocation) -@mapdata_api_router.get('/dynamiclocations/{dynamiclocation_id}/', - response={200: DynamicLocationSchema, **API404.dict(), **auth_responses}, - summary="Get dynamic location by ID") +@mapdata_api_router.get('/dynamiclocations/{dynamiclocation_id}/', summary="dynamic location by ID", + response={200: DynamicLocationSchema, **API404.dict(), **auth_responses}) @newapi_etag() def dynamiclocation_by_id(request, dynamiclocation_id: int): return mapdata_retrieve_endpoint(request, DynamicLocation, pk=dynamiclocation_id)