From 64088759f56336f428232c0929dedf9aaf32f62b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Laura=20Kl=C3=BCnder?= <laura@codingcatgirl.de>
Date: Mon, 4 Dec 2023 13:04:35 +0100
Subject: [PATCH] more API docs

---
 src/c3nav/api/api.py  | 13 +++++++++----
 src/c3nav/api/auth.py | 10 +++++-----
 2 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/src/c3nav/api/api.py b/src/c3nav/api/api.py
index d2857ea6..1ce7a7d1 100644
--- a/src/c3nav/api/api.py
+++ b/src/c3nav/api/api.py
@@ -1,8 +1,8 @@
 from django.conf import settings
-from ninja import Router as APIRouter
+from ninja import Router as APIRouter, Field as APIField
 from ninja import Schema
 
-from c3nav.api.auth import APIAuthMethod, auth_responses
+from c3nav.api.auth import APIKeyType, auth_responses
 from c3nav.api.utils import NonEmptyStr
 from c3nav.control.models import UserPermissions
 
@@ -13,8 +13,13 @@ class AuthStatusSchema(Schema):
     """
     Current auth state and permissions
     """
-    method: APIAuthMethod
-    readonly: bool
+    key_type: APIKeyType = APIField(
+        title="api key type",
+    )
+    readonly: bool = APIField(
+        title="read only",
+        description="if true, no API operations that modify data can be called"
+    )
     scopes: list[str]
 
 
diff --git a/src/c3nav/api/auth.py b/src/c3nav/api/auth.py
index 92673ca9..b2ea7e82 100644
--- a/src/c3nav/api/auth.py
+++ b/src/c3nav/api/auth.py
@@ -18,7 +18,7 @@ from c3nav.control.models import UserPermissions
 FakeRequest = namedtuple('FakeRequest', ('session', ))
 
 
-class APIAuthMethod(StrEnum):
+class APIKeyType(StrEnum):
     ANONYMOUS = 'anonymous'
     SESSION = 'session'
     SECRET = 'secret'
@@ -26,7 +26,7 @@ class APIAuthMethod(StrEnum):
 
 @dataclass
 class APIAuthDetails:
-    method: APIAuthMethod
+    key_type: APIKeyType
     readonly: bool
 
 
@@ -59,7 +59,7 @@ class APITokenAuth(HttpBearer):
 
         if token == "anonymous":
             return APIAuthDetails(
-                method=APIAuthMethod.ANONYMOUS,
+                key_type=APIKeyType.ANONYMOUS,
                 readonly=True,
             )
         elif token.startswith("session:"):
@@ -70,7 +70,7 @@ class APITokenAuth(HttpBearer):
                 raise APITokenInvalid
             request.user = user
             return APIAuthDetails(
-                method=APIAuthMethod.SESSION,
+                key_type=APIKeyType.SESSION,
                 readonly=False,
             )
         elif token.startswith("secret:"):
@@ -92,7 +92,7 @@ class APITokenAuth(HttpBearer):
             request.user_permissions = user_permissions
 
             return APIAuthDetails(
-                method=APIAuthMethod.SESSION,
+                key_type=APIKeyType.SESSION,
                 readonly=secret.readonly
             )
         raise APITokenInvalid