Document metadata ws endpoints

geomagio/api/secure/login.py

@@ -150,10 +150,11 @@ oauth.register(
 router = APIRouter()
 
 
-@router.get("/authorize")
+@router.get(
+    "/authorize",
+    description="Authorize callback after authenticating using OpenID",
+)
 async def authorize(request: Request):
-    """Authorize callback after authenticating using OpenID"""
-
     # finish login
     token = await oauth.openid.authorize_access_token(request)
 
@@ -171,9 +172,11 @@ async def authorize(request: Request):
     )
 
 
-@router.get("/login")
+@router.get(
+    "/login",
+    description="Redirect to OpenID provider.",
+)
 async def login(request: Request):
-    """Redirect to OpenID provider."""
     redirect_uri = request.url_for("authorize")
     if "127.0.0.1" not in redirect_uri:
         # 127.0.0.1 used for local dev, all others use https
@@ -185,9 +188,11 @@ async def login(request: Request):
     return await oauth.openid.authorize_redirect(request, redirect_uri)
 
 
-@router.get("/logout")
+@router.get(
+    "/logout",
+    description="Clear session and redirect to index page.",
+)
 async def logout(request: Request):
-    """Clear session and redirect to index page."""
     request.session.pop("token", None)
     request.session.pop("user", None)
     return RedirectResponse(
@@ -199,7 +204,9 @@ async def logout(request: Request):
     )
 
 
-@router.get("/user")
+@router.get(
+    "/user",
+    description="Get currently logged in user.",
+)
 async def user(request: Request, user: User = Depends(require_user())) -> User:
-    """Get currently logged in user."""
     return user

geomagio/api/secure/metadata.py

@@ -59,7 +59,11 @@ def get_metadata_query(
     )
 
 
-@router.post("/metadata", response_model=Metadata)
+@router.post(
+    "/metadata",
+    description="Save metadata in database",
+    response_model=Metadata,
+)
 async def create_metadata(
     request: Request,
     metadata: Metadata,
@@ -71,13 +75,22 @@ async def create_metadata(
     return Response(metadata.json(), status_code=201, media_type="application/json")
 
 
-@router.get("/metadata", response_model=List[Metadata])
+@router.get(
+    "/metadata",
+    description="Search metadata by query parameters",
+    name="Request metadata",
+    response_model=List[Metadata],
+)
 async def get_metadata(query: MetadataQuery = Depends(get_metadata_query)):
     metas = await MetadataDatabaseFactory(database=database).get_metadata(params=query)
     return metas
 
 
-@router.get("/metadata/history", response_model=List[Metadata])
+@router.get(
+    "/metadata/history",
+    description="Search historical metadata by query parameters",
+    response_model=List[Metadata],
+)
 async def get_metadata_history(query: MetadataQuery = Depends(get_metadata_query)):
     metas = await MetadataDatabaseFactory(database=database).get_metadata(
         params=query, history=True
@@ -85,12 +98,20 @@ async def get_metadata_history(query: MetadataQuery = Depends(get_metadata_query
     return metas
 
 
-@router.get("/metadata/{id}", response_model=Metadata)
+@router.get(
+    "/metadata/{id}",
+    description="Search metadata by database id",
+    response_model=Metadata,
+)
 async def get_metadata_by_id(id: int):
     return await MetadataDatabaseFactory(database=database).get_metadata_by_id(id=id)
 
 
-@router.get("/metadata/{metadata_id}/history", response_model=List[Metadata])
+@router.get(
+    "/metadata/{metadata_id}/history",
+    description="Search metadata version history by database id",
+    response_model=List[Metadata],
+)
 async def get_metadata_history_by_metadata_id(
     metadata_id: int,
 ):
@@ -101,7 +122,11 @@ async def get_metadata_history_by_metadata_id(
     )
 
 
-@router.get("/metadata/history/{id}", response_model=Metadata)
+@router.get(
+    "/metadata/history/{id}",
+    description="Search historical metadata by database id",
+    response_model=Metadata,
+)
 async def get_metadata_history_by_id(id: int):
     metadata = await MetadataDatabaseFactory(
         database=database
@@ -111,7 +136,11 @@ async def get_metadata_history_by_id(id: int):
     return metadata
 
 
-@router.put("/metadata/{id}", response_model=Metadata)
+@router.put(
+    "/metadata/{id}",
+    description="Edit metadata from older version",
+    response_model=Metadata,
+)
 async def update_metadata(
     id: int,
     metadata: Metadata = Body(...),