[doc] add docstrings for halfapi routes

halfapi/halfapi.py

@@ -158,6 +158,12 @@ class HalfAPI(Starlette):
         return __version__
 
     async def version_async(self, request, *args, **kwargs):
+        """
+        description: Version route
+        responses:
+          200:
+            description: Currently running HalfAPI's version
+        """
         return Response(self.version)
 
     @staticmethod
@@ -174,6 +180,16 @@ class HalfAPI(Starlette):
         """
 
         async def get_user(request, *args, **kwargs):
+            """
+            description: WhoAmI route
+            responses:
+              200:
+                description: The currently logged-in user
+                content:
+                  application/json:
+                    schema:
+                      type: object
+            """
             return ORJSONResponse({'user':request.user})
 
         yield Route('/whoami', get_user)

halfapi/lib/schemas.py

@@ -27,8 +27,12 @@ SCHEMAS = SchemaGenerator(
 
 async def schema_json(request, *args, **kwargs):
     """
-    description: Returns the current API routes description (OpenAPI v3)
+    description: |
-                 as a JSON object
+      Returns the current API routes description (OpenAPI v3)
+      as a JSON object
+    responses:
+      200:
+        description: API Schema in OpenAPI v3 format
     """
     return ORJSONResponse(
         SCHEMAS.get_schema(routes=request.app.routes))