From 6a7c305468ce9c96f24865a4a16bdf10254ba649 Mon Sep 17 00:00:00 2001
From: Richard <richard.bowman@cantab.net>
Date: Wed, 14 Jul 2021 19:15:26 +0100
Subject: [PATCH] Started adding more content to openapi

---
 openflexure_microscope/api/app.py     |  3 ++
 openflexure_microscope/api/openapi.py | 43 +++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 openflexure_microscope/api/openapi.py

diff --git a/openflexure_microscope/api/app.py b/openflexure_microscope/api/app.py
index 1739bec0..6e3c4e0e 100644
--- a/openflexure_microscope/api/app.py
+++ b/openflexure_microscope/api/app.py
@@ -39,6 +39,7 @@ from openflexure_microscope.paths import (
     OPENFLEXURE_VAR_PATH,
     logs_file_path,
 )
+from .openapi import add_spec_extras
 
 
 # Custom RotatingFileHandler subclass
@@ -209,6 +210,8 @@ def routes():
 def api_v1_catch_all(path):  # pylint: disable=W0613
     abort(410, "API v1 is no longer in use. Please upgrade your client.")
 
+add_spec_extras(labthing.spec)
+
 
 # Automatically clean up microscope at exit
 def cleanup():
diff --git a/openflexure_microscope/api/openapi.py b/openflexure_microscope/api/openapi.py
new file mode 100644
index 00000000..d96aa491
--- /dev/null
+++ b/openflexure_microscope/api/openapi.py
@@ -0,0 +1,43 @@
+
+
+API_TAGS = [
+    {
+        "name": "actions",
+        "description": (
+            "Actions that can be run on the microscope.  These endpoints represent "
+            "actions that many not complete immediately, so they run on the server "
+            "as `Action` objects and their status can be queried using the links "
+            "embedded in the JSON action description."
+        ),
+        "externalDocs": "https://iot.mozilla.org/wot/#action-resource",
+    },
+    {
+        "name": "properties",
+        "description": (
+            "Properties can be read and/or written to, and affect the "
+            "state of the microscope."
+        ),
+        "externalDocs": "https://iot.mozilla.org/wot/#property-resource",
+    },
+    {
+        "name": "captures",
+        "description": "",
+        "externalDocs": ""
+    },
+    {
+        "name": "extensions",
+        "description": "",
+        "externalDocs": ""
+    },
+    {
+        "name": "events",
+        "description": "",
+        "externalDocs": ""
+    }
+]
+
+def add_spec_extras(spec):
+    """Add extra documentation and features to the OpenAPI spec"""
+    # Add a list of tags, so we can control ordering and add descriptions
+    for t in API_TAGS:
+        spec.tag(t)