Openapi spec tweaks

nfelger · Oct 19, 2020 · 59414f3 · 59414f3
1 parent 275e087
commit 59414f3
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 16 deletions.
diff --git a/rip_api/api/__init__.py b/rip_api/api/__init__.py
@@ -5,10 +5,11 @@
 from fastapi import Path, Query
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.middleware.gzip import GZipMiddleware
+from fastapi.openapi.utils import get_openapi
 import starlette
 
 from rip_api import PUBLIC_ASSET_ROOT, api_schemas, db, models, urls
-from .docs import tags_metadata, description_api, description_page, description_per_page
+from .docs import tags_metadata, description_api, description_page, description_per_page, docs_html, customize_openapi_schema
 from .errors import (
     ApiException,
     api_exception_handler,
@@ -43,6 +44,30 @@
 v1.exception_handler(fastapi.exceptions.RequestValidationError)(validation_error_handler)
 
 
+def custom_openapi():
+    # cf. https://fastapi.tiangolo.com/advanced/extending-openapi/
+    if v1.openapi_schema:
+        return v1.openapi_schema
+
+    openapi_schema = get_openapi(
+        title=v1.title,
+        openapi_version=v1.openapi_version,
+        version=v1.version,
+        description=v1.description,
+        routes=v1.routes,
+        tags=v1.openapi_tags,
+        servers=v1.servers,
+    )
+
+    customize_openapi_schema(openapi_schema)
+
+    v1.openapi_schema = openapi_schema
+    return v1.openapi_schema
+
+
+v1.openapi = custom_openapi
+
+
 class ListLawsIncludeOptions(Enum):
     all_fields = "all_fields"
 
@@ -222,21 +247,7 @@ async def bulk_download_laws_tarball():
     include_in_schema=False,
 )
 async def rapidoc():
-    return f"""
-        <!doctype html>
-        <html>
-            <head>
-                <meta charset="utf-8">
-                <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
-            </head>
-            <body>
-                <rapi-doc spec-url="/v1{v1.openapi_url}" show-header="false"
-                          allow-authentication="false" allow-server-selection="false">
-                </rapi-doc>
-            </body>
-        </html>
-    """
-
+    return docs_html(v1)
 
 @v1.get("/", include_in_schema=False)
 async def redirect_root():

diff --git a/rip_api/api/docs.py b/rip_api/api/docs.py
@@ -120,3 +120,48 @@
 
 description_page = "Result page number"
 description_per_page = "Number of items per page"
+
+
+def docs_html(v1):
+    return f"""
+        <!doctype html>
+        <html>
+            <head>
+                <meta charset="utf-8">
+                <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
+            </head>
+            <body>
+                <rapi-doc spec-url="/v1{v1.openapi_url}" show-header="false"
+                          allow-authentication="false" allow-server-selection="false">
+                </rapi-doc>
+            </body>
+        </html>
+    """
+
+
+redirect_spec = {
+    "description": "Redirect Response to download location",
+    "application/gzip": {
+        "schema": {
+            "type": "string",
+            "format": "binary"
+        }
+    }
+}
+
+
+def customize_openapi_schema(openapi_schema):
+    """
+    Some aspects of the openapi schema are not easily changed using fastapi, so we modify it directly.
+    """
+
+    for path, path_dict in openapi_schema["paths"].items():
+        # Remove wrong default 422 - better undocumented than documented incorrectly!
+        for method_dict in path_dict.values():
+            if "422" in method_dict["responses"]:
+                del method_dict["responses"]["422"]
+
+        # Describe correct redirect responses
+        if path.startswith("/bulk_downloads"):
+            for method_dict in path_dict.values():
+                method_dict["responses"][302] = redirect_spec