Better response descriptions for builtin endpoints

Author: rwb27

src/labthings/default_views/actions.py

@@ -7,21 +7,29 @@
 from ..views import View
 
 
+
 class ActionQueueView(View):
     """List of all actions from the session"""
 
     def get(self):
         """Action queue
-        ---
-        description: Queue of most recent actions in the session
-        summary: Queue of most recent actions in the session
-        responses:
-            200:
-                content:
-                    application/json:
-                        schema: ActionSchema
+        
+        This endpoint returns a list of all actions that have run since 
+        the server was started, including ones that have completed and 
+        actions that are still running.  Each entry includes links to 
+        manage and inspect that action.
         """
         return ActionSchema(many=True).dump(current_labthing().actions.threads)
+    get.responses = {
+        "200": {
+            "description": "List of Action objects",
+            "content": {
+                "application/json": {
+                    "schema": ActionSchema(many=True)
+                }
+            }
+        }
+    }
 
 
 class ActionObjectView(View):
@@ -35,14 +43,10 @@ class ActionObjectView(View):
 
     def get(self, task_id):
         """Show the status of an Action
-        ---
-        description: Status of an Action
-        summary: Status of an Action
-        responses:
-            200:
-                content:
-                    application/json:
-                        schema: ActionSchema
+        
+        A `GET` request will return the current status
+        of an action, including logs.  For completed
+        actions, it will include the return value.
         """
         task_dict = current_labthing().actions.to_dict()
 
@@ -52,18 +56,25 @@ def get(self, task_id):
         task = task_dict.get(task_id)
 
         return ActionSchema().dump(task)
+    get.responses = {
+        "200": {
+            "description": "Action object",
+            "content": {
+                "application/json": {
+                    "schema": ActionSchema
+                }
+            }
+        },
+        "404": {
+            "description": "Action not found"
+        }
+    }
 
     @use_args({"timeout": fields.Int()})
     def delete(self, args, task_id):
         """Cancel a running Action
-        ---
-        description: Cancel an Action
-        summary: Cancel an Action
-        responses:
-            200:
-                content:
-                    application/json:
-                        schema: ActionSchema
+        
+        A `DELETE` request will stop a running action.
         """
         timeout = args.get("timeout", None)
         task_dict = current_labthing().actions.to_dict()
@@ -74,3 +85,16 @@ def delete(self, args, task_id):
         task = task_dict.get(task_id)
         task.stop(timeout=timeout)
         return ActionSchema().dump(task)
+    delete.responses = {
+        "200": {
+            "description": "Action object that was cancelled",
+            "content": {
+                "application/json": {
+                    "schema": ActionSchema
+                }
+            }
+        },
+        "404": {
+            "description": "Action not found"
+        }
+    }

src/labthings/default_views/extensions.py

@@ -14,13 +14,16 @@ def get(self):
 
         Returns a list of Extension representations, including basic documentation.
         Describes server methods, web views, and other relevant Lab Things metadata.
-        ---
-        description: Extensions list
-        summary: Extensions list
-        responses:
-            200:
-                content:
-                    application/json:
-                        schema: ExtensionSchema
         """
         return ExtensionSchema(many=True).dump(registered_extensions().values() or [])
+    
+    get.responses = {
+        "200": {
+            "description": "A list of available extensions and their properties",
+            "content": {
+                "application/json":{
+                    "schema": ExtensionSchema
+                }
+            }
+        }
+    }

src/labthings/default_views/root.py

@@ -12,3 +12,18 @@ def get(self):
         summary: Thing Description
         """
         return current_labthing().thing_description.to_dict()
+
+    get.summary = "Thing Description"
+    get.description = (
+        "A W3C compliant Thing Description is a JSON representation\n"
+        "of the API, including links to different endpoints.\n"
+        "You can browse it directly (e.g. in Firefox), though for \n"
+        "interactive API documentation you should try the swagger-ui \n"
+        "docs, at `docs/swagger-ui/`"
+    )
+    get.responses = {
+        "200": {
+            "description": "W3C Thing Description",
+            "content": {"application/json":{}},
+        }
+    }

src/labthings/views/builder.py

@@ -36,6 +36,17 @@ def _get(_, path=""):
                 return abort(404)
             return send_file(indexes[0])
 
+    _get.summary = "Serve static files"
+    _get.description = "Files and folders within this path will be served from a static directory."
+    _get.responses = {
+        "200": {
+            "description": "Static file",
+        },
+        "404": {
+            "description": "Static file not found",
+        },
+    }
+
     # Generate a basic property class
     generated_class = type(name, (View, object), {"get": _get})