Add message to Swagger UI page encouraging visitors to use Runtime API instead

nmdc_server/app.py

@@ -15,6 +15,7 @@
 from nmdc_server.config import settings
 from nmdc_server.database import after_cursor_execute, before_cursor_execute, listen
 from nmdc_server.static_files import static_path
+from nmdc_server.swagger_ui.helpers import load_template
 
 
 def attach_sentry(app: FastAPI):
@@ -41,14 +42,20 @@ def create_app(env: typing.Mapping[str, str]) -> FastAPI:
         listen(Engine, "before_cursor_execute", before_cursor_execute)
         listen(Engine, "after_cursor_execute", after_cursor_execute)
 
+    # Load the description template and replace the placeholder(s) within it.
+    description = (
+        load_template("description.template.md")
+        .replace("{{ developer_tools_url }}", "/user")
+        .replace("{{ runtime_api_url }}", "https://api.microbiomedata.org")
+        .replace("{{ nmdc_data_portal_url }}", "https://data.microbiomedata.org")
+        .replace(
+            "{{ nmdc_submission_portal_url }}", "https://data.microbiomedata.org/submission/home"
+        )
+    )
+
     app = FastAPI(
         title="NMDC Data and Submission Portal API",
-        description="""
-To use authenticated endpoints, you must first obtain an Access Token by following the
-instructions in the Developer Tools section <a href="/user">here</a>. Once you have an Access
-Token, click the "Authorize" button on this page. In the popup, paste the token in the "Value"
-field and click "Authorize".
-""",
+        description=description,
         version=__version__,
         docs_url="/api/docs",
         openapi_url="/api/openapi.json",

nmdc_server/swagger_ui/helpers.py

@@ -0,0 +1,19 @@
+from importlib import resources
+
+
+def load_template(resource_path: str) -> str:
+    r"""
+    Returns the contents of a template file as a string.
+
+    Note: We do this via `importlib.resources` instead of a regular `open()` so
+          that the path is accurate both when this script is run in a development
+          environment and when this script is run when installed from PyPI,
+          instead of it only being accurate in the former case.
+          Reference: https://docs.python.org/3.9/library/importlib.html#importlib.resources.files
+
+    Note: This function was copied from the `refscan` repository, at:
+          https://github.com/microbiomedata/refscan/blob/a30ece13/refscan/grapher.py#L31-L42
+    """
+
+    package_name = "nmdc_server.swagger_ui.templates"
+    return resources.files(package_name).joinpath(resource_path).read_text(encoding="utf-8")

nmdc_server/swagger_ui/templates/description.template.md

@@ -0,0 +1,18 @@
+<!-- 
+    Note: The `description` kwarg of the `FastAPI` constructor supports CommonMark syntax,
+          according to the constructor's docstring.
+-->
+
+This API was designed to be accessed by
+the [NMDC Data Portal]({{ nmdc_data_portal_url }}) and
+the [NMDC Submission Portal]({{ nmdc_submission_portal_url }}) only.
+
+**Want to access NMDC data from your own scripts and programs?**
+Check out the [NMDC Runtime API]({{ runtime_api_url }}), which was
+designed to be accessed by third-party scripts, programs, and other HTTP clients.
+
+**NMDC developers:** To use authenticated endpoints of this API,
+you must first obtain an Access Token by following the instructions in the
+Developer Tools section [here]({{ developer_tools_url }}).
+Once you have an Access Token, click the "Authorize" button on this page.
+In the popup, paste the token in the "Value" field and click "Authorize".