From 828d7819383f5082e47e4897eeaa155584e1d5d5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Laura=20Kl=C3=BCnder?= <laura@codingcatgirl.de>
Date: Sun, 3 Dec 2023 19:04:23 +0100
Subject: [PATCH] improve api documentation for redoc

---
 src/c3nav/api/newapi.py         |  5 +++--
 src/c3nav/api/ninja.py          | 31 +++++++++++++++++++++----------
 src/c3nav/mapdata/newapi/map.py |  3 ++-
 3 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/src/c3nav/api/newapi.py b/src/c3nav/api/newapi.py
index 5a592944..03b79f0e 100644
--- a/src/c3nav/api/newapi.py
+++ b/src/c3nav/api/newapi.py
@@ -18,7 +18,8 @@ class AuthStatusSchema(Schema):
     scopes: list[str]
 
 
-@auth_api_router.get('/status/', summary="get current auth details",
+@auth_api_router.get('/status/', summary="get status",
+                     description="Returns details about the current authentication",
                      response={200: AuthStatusSchema, **auth_responses})
 def get_status(request):
     permissions = UserPermissions.get_for_user(request.user)
@@ -41,7 +42,7 @@ class APITokenSchema(Schema):
 
 
 @auth_api_router.get('/session/', response=APITokenSchema, auth=None,
-                     summary="Get API token tied to the current session")
+                     summary="get session-bound token")
 def session_token(request):
     session_id = request.COOKIES.get(settings.SESSION_COOKIE_NAME, None)
     return {"token": "anonymous" if session_id is None else f"session:{session_id}"}
diff --git a/src/c3nav/api/ninja.py b/src/c3nav/api/ninja.py
index 34046d68..ed0d4813 100644
--- a/src/c3nav/api/ninja.py
+++ b/src/c3nav/api/ninja.py
@@ -31,15 +31,20 @@ class SwaggerAndRedoc(DocsBase):
 
 
 description = """
-We provide two API documentation viewers:
-
-* [Redoc](/api/v2/): more comprehensive and clean *(default)*
-* [Swagger](/api/v2/?swagger): less good, but has a built-in API client 
 
 Nearly all endpoints require authentication, but guest authentication can be used.
 
-API endpoints may change to add more features and properties,
-but no properties will be removed without a version change.
+API endpoints may change to add more features and properties, but we will attempt to keep it backwards-compatible.
+
+We provide two API documentation viewers:
+
+* [Redoc](/api/v2/): more comprehensive and clean *(default)*
+* [Swagger](/api/v2/?swagger): less good, but has a built-in API client
+
+We recommend reading the documentation using Redoc, and either using the Code examples provided next to each request,
+or switching to swagger if you want an in-browser API client. 
+
+
 """.strip()
 ninja_api = c3navAPI(
     title="c3nav API",
@@ -47,41 +52,47 @@ ninja_api = c3navAPI(
     description=description,
 
     docs_url="/",
-    docs=Swagger(settings={
-        "persistAuthorization": True,
-        "defaultModelRendering": "model",
-    }),
+    docs=SwaggerAndRedoc(),
 
     auth=APITokenAuth(),
 
     openapi_extra={
+
+        
         "tags": [
             {
                 "name": "auth",
+                "x-displayName": "Authentication",
                 "description": "Get and manage API access",
             },
             {
                 "name": "map",
+                "x-displayName": "Map access",
                 "description": "Common map endpoints",
             },
             {
                 "name": "routing",
+                "x-displayName": "Routing",
                 "description": "Calculate routes",
             },
             {
                 "name": "positioning",
+                "x-displayName": "Positioning",
                 "description": "Determine your position",
             },
             {
                 "name": "mapdata",
+                "x-displayName": "Raw map data",
                 "description": "Access the raw map data",
             },
             {
                 "name": "editor",
+                "x-displayName": "Editor",
                 "description": "Endpoints for the editor and to interface with the editor",
             },
             {
                 "name": "mesh",
+                "x-displayName": "Mesh",
                 "description": "Manage the location node mesh network",
             },
         ],
diff --git a/src/c3nav/mapdata/newapi/map.py b/src/c3nav/mapdata/newapi/map.py
index 79b63092..fa9e6b65 100644
--- a/src/c3nav/mapdata/newapi/map.py
+++ b/src/c3nav/mapdata/newapi/map.py
@@ -27,7 +27,8 @@ from c3nav.mapdata.utils.user import can_access_editor
 map_api_router = APIRouter(tags=["map"])
 
 
-@map_api_router.get('/bounds/', summary="Get map boundaries",
+@map_api_router.get('/bounds/', summary="get boundaries",
+                    description="get maximum boundaries of everything on the map",
                     response={200: BoundsSchema, **auth_responses})
 @newapi_etag(permissions=False)
 def bounds(request):