Merge pull request #1081 from lsst-sqre/tickets/DM-46019

DM-46019: Switch to new documenteer REST API method

.dockerignore

@@ -3,6 +3,9 @@
 ui/.cache/
 ui/node_modules/
 
+# VSCode
+.vscode/
+
 # Everything below this point is a copy of .gitignore.
 
 # Byte-compiled / optimized / DLL files
@@ -77,8 +80,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/api/
-docs/_static/*.png
+docs/_static/openapi.json
+docs/dev/internals/
 
 # PyBuilder
 target/
@@ -142,9 +145,5 @@ dmypy.json
 # pytype static type analyzer
 .pytype/
 
-# Emacs temporary files
-.#*
-\#*#
-
-# Modified to set up the local development server.
-/examples/secrets/github-client-secret
+# macOS
+.DS_Store

.gitignore

@@ -69,10 +69,9 @@ instance/
 .scrapy
 
 # Sphinx documentation
-/docs/_build/
-/docs/_static/openapi.json
-/docs/_static/*.png
-/docs/dev/internals/
+docs/_build/
+docs/_static/openapi.json
+docs/dev/internals/
 
 # PyBuilder
 target/
@@ -136,9 +135,5 @@ dmypy.json
 # pytype static type analyzer
 .pytype/
 
-# Emacs temporary files
-.#*
-\#*#
-
-# Modified to set up the local development server.
-/examples/secrets/github-client-secret
+# macOS
+.DS_Store

docs/api.rst

@@ -2,9 +2,4 @@
 REST API
 ########
 
-Once Gafaelfawr is installed, API documentation is available at ``/auth/docs`` and ``/auth/redoc``.
-The latter provides somewhat more detailed information.
-
-You can view a pregenerated version of the Redoc documentation for the current development version of Gafaelfawr by following the link below.
-
-`REST API <rest.html>`__
+This is a stub page for the API.

docs/conf.py

@@ -9,15 +9,3 @@
     "_rst_epilog.rst",
     "_templates/**",
 ]
-redoc = [
-    {
-        "name": "REST API",
-        "page": "rest",
-        "spec": "_static/openapi.json",
-        "embed": True,
-        "opts": {"hide-hostname": True},
-    }
-]
-redoc_uri = (
-    "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"
-)

docs/documenteer.toml

@@ -2,6 +2,14 @@
 title = "Gafaelfawr"
 copyright = "2020-2022 Association of Universities for Research in Astronomy, Inc. (AURA)"
 
+[project.openapi]
+openapi_path = "_static/openapi.json"
+doc_path = "api"
+
+[project.openapi.generator]
+function = "gafaelfawr.main:create_openapi"
+keyword_args = {add_back_link = true}
+
 [project.python]
 package = "gafaelfawr"
 

src/gafaelfawr/cli.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import asyncio
-import json
 import os
 import subprocess
 import sys
@@ -15,7 +14,6 @@
 import uvicorn
 from alembic.config import Config
 from cryptography.fernet import Fernet
-from fastapi.openapi.utils import get_openapi
 from safir.asyncio import run_with_asyncio
 from safir.click import display_help
 from safir.database import create_database_engine
@@ -30,7 +28,7 @@
 from .dependencies.config import config_dependency
 from .factory import Factory
 from .keypair import RSAKeyPair
-from .main import create_app
+from .main import create_openapi
 from .metrics import StateMetrics
 from .models.token import Token
 from .schema import Base
@@ -257,22 +255,12 @@ async def maintenance(*, config_path: Path | None) -> None:
 )
 def openapi_schema(*, add_back_link: bool, output: Path | None) -> None:
     """Generate the OpenAPI schema."""
-    app = create_app(load_config=False, validate_schema=False)
-    description = app.description
-    if add_back_link:
-        description += "\n\n[Return to Gafaelfawr documentation](api.html)."
-    schema = get_openapi(
-        title=app.title,
-        description=description,
-        version=app.version,
-        routes=app.routes,
-    )
+    schema = create_openapi(add_back_link=add_back_link)
     if output:
         output.parent.mkdir(exist_ok=True)
-        with output.open("w") as f:
-            json.dump(schema, f)
+        output.write_text(schema)
     else:
-        json.dump(schema, sys.stdout)
+        sys.stdout.write(schema)
 
 
 @main.command()

src/gafaelfawr/main.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 from collections.abc import AsyncIterator, Coroutine
 from contextlib import asynccontextmanager
@@ -10,6 +11,7 @@
 
 import structlog
 from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
 from fastapi.staticfiles import StaticFiles
 from opentelemetry.sdk.metrics.export import MetricReader
 from safir.dependencies.db_session import db_session_dependency
@@ -188,3 +190,31 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
     app.exception_handler(ClientRequestError)(client_request_error_handler)
 
     return app
+
+
+def create_openapi(*, add_back_link: bool = False) -> str:
+    """Generate the OpenAPI schema.
+
+    Parameters
+    ----------
+    add_back_link
+        Whether to add a back link to the parent page to the description.
+        This is useful when the schema will be rendered as part of the
+        documentation.
+
+    Returns
+    -------
+    str
+        OpenAPI schema as serialized JSON.
+    """
+    app = create_app(load_config=False, validate_schema=False)
+    description = app.description
+    if add_back_link:
+        description += "\n\n[Return to Gafaelfawr documentation](.)."
+    schema = get_openapi(
+        title=app.title,
+        description=description,
+        version=app.version,
+        routes=app.routes,
+    )
+    return json.dumps(schema)

tox.ini

@@ -69,7 +69,6 @@ commands =
     rm -rf docs/dev/internals
     # https://github.com/sphinx-contrib/redoc/issues/48
     rm -f docs/_build/html/_static/redoc.js
-    gafaelfawr openapi-schema --add-back-link --output docs/_static/openapi.json
     sphinx-build -W --keep-going -n -T -b html -d {envtmpdir}/doctrees docs docs/_build/html
 
 [testenv:docs-linkcheck]