Serve the OpenAPI document at /openapi.json, as NodeNorm Redis does

README.md

@@ -28,3 +28,14 @@ https://github.com/biothings/biothings_explorer/blob/main/docs/README-maintainin
 The documentation is maintained at the [biothings_explorer](https://github.com/biothings/biothings_explorer) repository,
 as each knowledgebase API will be integrated into the [BioThings Explorer application](https://explorer.biothings.io) become
 a Translator's standard KP (Knowledge Provider) API.
+
+## OpenAPI document
+
+The API is described by `src/nodenorm/webapp/openapi.json`, which is written by hand and served
+verbatim at `/openapi.json`, as NodeNorm Redis and most Translator services serve theirs, and also
+at the older `/webapp/openapi.json`; the Swagger UI at `/` renders it. `/status` reports its `info.version` as the API version, so bump that when the API
+changes. `tests/test_openapi.py` checks that the document validates and that its paths, methods,
+query parameters, POST body fields and the `SetIDResponse` schema match the handlers, so a handler
+change that isn't reflected in the JSON fails the test suite. The parameter and body checks find
+what a handler reads by scanning its source for `get_argument("…")` and `.get("…")` calls with a
+literal name, so read new parameters and body fields that way.

docker/configuration/config.json

@@ -28,6 +28,6 @@
         "OPENTELEMETRY_SERVICE_NAME": "NodeNorm",
         "OPENTELEMETRY_JAEGER_HOST": "http://jaeger-otel-collector.sri",
         "OPENTELEMETRY_JAEGER_PORT": 4318,
-        "OPENTELEMETRY_EXCLUDED_URLS": ["^/$", "^/status$", "^/version$", "^/webapp", "^/favicon\\.ico$"]
+        "OPENTELEMETRY_EXCLUDED_URLS": ["^/$", "^/status$", "^/version$", "^/webapp", "^/openapi\\.json$", "^/favicon\\.ico$"]
     }
 }

pyproject.toml

@@ -54,6 +54,7 @@ tests = [
     "pytest >= 8.1.1",
     "pytest-asyncio >= 0.23.8",
     "pytest-randomly",
+    "openapi-spec-validator",
 ]
 
 telemetry = [

src/nodenorm/config/config.default.json

@@ -28,6 +28,6 @@
         "OPENTELEMETRY_SERVICE_NAME": "NodeNorm",
         "OPENTELEMETRY_JAEGER_HOST": "http://localhost",
         "OPENTELEMETRY_JAEGER_PORT": 4318,
-        "OPENTELEMETRY_EXCLUDED_URLS": ["^/$", "^/status$", "^/version$", "^/webapp", "^/favicon\\.ico$"]
+        "OPENTELEMETRY_EXCLUDED_URLS": ["^/$", "^/status$", "^/version$", "^/webapp", "^/openapi\\.json$", "^/favicon\\.ico$"]
     }
 }

src/nodenorm/handlers/__init__.py

@@ -42,8 +42,14 @@ def build_handlers() -> dict[str, tuple[str, Callable]]:
     handler_collection.append(index_handler)
 
     # This redirect ensures we default so the favicon icon can be found in the webapp directory
-    favicon_handler = (r"/favicon.ico", tornado.web.RedirectHandler, {"url": "/webapp/swaggerui/favicon-32x32.png"})
+    favicon_handler = (r"/favicon\.ico", tornado.web.RedirectHandler, {"url": "/webapp/swaggerui/favicon-32x32.png"})
     handler_collection.append(favicon_handler)
 
+    # The OpenAPI document is served at the root, where NodeNorm Redis (FastAPI) and most Translator
+    # services serve theirs. The asset handler above also serves it at /webapp/openapi.json, the
+    # address Babel Validation's targets and the Translator diagram are configured with.
+    openapi_handler = (r"/(openapi\.json)", tornado.web.StaticFileHandler, {"path": str(webapp_directory)})
+    handler_collection.append(openapi_handler)
+
     handlers = {handler[0]: handler for handler in handler_collection}
     return handlers

src/nodenorm/handlers/conflations.py

@@ -1,17 +1,14 @@
-import logging
-
 from nodenorm.handlers.base import NodeNormalizationBaseHandler
 
-logger = logging.getLogger(__name__)
+ALLOWED_CONFLATIONS = ["GeneProtein", "DrugChemical"]
 
 
 class ValidConflationsHandler(NodeNormalizationBaseHandler):
     name = "allowed-conflations"
 
     async def get(self):
-        conflations = ["GeneProtein", "DrugChemical"]
-        self.finish(conflations)
+        # Wrapped in an object, as NodeNorm Redis does. Tornado also refuses to write a bare list.
+        self.finish({"conflations": ALLOWED_CONFLATIONS})
 
     async def head(self):
-        conflations = ["GeneProtein", "DrugChemical"]
-        self.finish(conflations)
+        await self.get()

src/nodenorm/handlers/normalized_nodes.py

@@ -76,7 +76,7 @@ async def post(self):
 
         Example body
         {
-          "curie": [
+          "curies": [
             "MESH:D014867",
             "NCIT:C34373"
           ]

src/nodenorm/handlers/semantic_types.py

@@ -33,7 +33,7 @@ async def get(self) -> dict:
             biolink_type = bucket["key"]
             semantic_types.add(biolink_type)
             for ancestor in toolkit.get_ancestors(biolink_type):
-                semantic_types.add(toolkit.get_element(ancestor)["class_uri"].lower())
+                semantic_types.add(toolkit.get_element(ancestor)["class_uri"])
 
         semantic_type_response = {"semantic_types": {"types": list(semantic_types)}}
         self.finish(semantic_type_response)

src/nodenorm/webapp/index.html

@@ -22,7 +22,7 @@
     // Initialize Swagger UI
     window.onload = function() {
       const ui = SwaggerUIBundle({
-        url: "/webapp/openapi.json",
+        url: "/openapi.json",
         dom_id: '#swagger-ui',
         presets: [
           SwaggerUIBundle.presets.apis,