Documentation for API endpoints

src/main.py

@@ -12,7 +12,9 @@
 SESSION_SECRET_KEY = os.getenv("SESSION_SECRET_KEY")
 
 log = logging.getLogger(__name__)
-app = FastAPI()
+app = FastAPI(
+    title="Teuthology API", description="REST API for executing Teuthology commands"
+)
 
 
 @app.get("/")

src/routes/kill.py

@@ -12,19 +12,68 @@
 )
 
 
-@router.post("/", status_code=200)
+@router.post(
+    "/",
+    status_code=200,
+    responses={
+        200: {
+            "description": "Run killed successfully",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "type": "object",
+                        "properties": {
+                            "log": {
+                                "type": "array",
+                                "description": "List of logs while executing teuthology-kill",
+                                "items": {"type": "string"},
+                            },
+                            "kill": {
+                                "type": "array",
+                                "description": "Teuthology-kill executed successfully",
+                                "items": {"type": "string"},
+                            },
+                        },
+                        "example": '{"kill": "success"}',
+                    }
+                }
+            },
+        },
+        400: {
+            "description": "Missing argument(s) in request body",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "type": "string",
+                        "example": "--run is a required argument",
+                    }
+                }
+            },
+        },
+        401: {
+            "description": "Authorization error: Either user is not logged in or doesn't have the permission to kill the run",
+            "content": {
+                "application/json": {
+                    "schema": {"type": "string", "example": "You need to be logged in"}
+                }
+            },
+        },
+        500: {
+            "description": "Error while executing teuthology command",
+            "content": {"application/json": {"schema": {"type": "string"}}},
+        },
+    },
+)
 def create_run(
     request: Request,
     args: KillArgs,
     logs: bool = False,
     access_token: str = Depends(get_token),
 ):
     """
-    POST route for killing a run or a job.
+    Endpoint for killing a run or a job.
 
-    Note: I needed to put `request` before `args`
-    or else it will SyntaxError: non-dafault
-    argument follows default argument error.
+    Requires user's GitHub `access_token` for authorization.
     """
     args = args.dict(by_alias=True)
     return run(args, logs, access_token, request)

src/schemas/kill.py

@@ -16,3 +16,20 @@ class KillArgs(BaseArgs):
     jobspec: Union[str, None] = Field(default=None, alias="--jobspec")
     machine_type: Union[str, None] = Field(default="default", alias="--machine-type")
     archive: Union[str, None] = Field(default=None, alias="--archive")
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "--dry-run": False,
+                    "--non-interactive": False,
+                    "--verbose": 1,
+                    "--help": False,
+                    "--user": "<sepia_username>",
+                    "--run": "<run_title>",
+                    "--job": [1, 2],
+                    "--machine-type": "smithi",
+                }
+            ]
+        }
+    }