Fix: Swagger UI for indexer is a stub (#5051)

lambdas/indexer/app.py

@@ -28,6 +28,7 @@
     SignatureHelper,
 )
 from azul.indexer.index_controller import (
+    Action,
     IndexController,
 )
 from azul.indexer.log_forwarding_controller import (
@@ -38,6 +39,11 @@
 )
 from azul.openapi import (
     format_description,
+    params,
+    schema,
+)
+from azul.openapi.spec import (
+    AuxSpec,
 )
 
 log = logging.getLogger(__name__)
@@ -46,10 +52,8 @@
     'openapi': '3.0.1',
     'info': {
         'title': config.indexer_name,
-        # FIXME: Swagger UI for indexer is a stub
-        #        https://github.com/DataBiosphere/azul/issues/5051
         'description': format_description('''
-            This is the indexer component for Azul.
+            This is the internal API for Azul's indexer component.
         '''),
         'version': '1.0'
     }
@@ -103,14 +107,17 @@ def static_resource(file):
     return app.swagger_resource(file)
 
 
-@app.route('/openapi', methods=['GET'], cors=True)
+aux_spec = AuxSpec(app_name='indexer')
+
+
+@app.route('/openapi', methods=['GET'], cors=True, **aux_spec.openapi())
 def openapi():
     return Response(status_code=200,
                     headers={'content-type': 'application/json'},
                     body=app.spec())
 
 
-@app.route('/version', methods=['GET'], cors=True)
+@app.route('/version', methods=['GET'], cors=True, **aux_spec.version())
 def version():
     from azul.changelog import (
         compact_changes,
@@ -121,27 +128,27 @@ def version():
     }
 
 
-@app.route('/health', methods=['GET'], cors=True)
+@app.route('/health', methods=['GET'], cors=True, **aux_spec.full_health())
 def health():
     return app.health_controller.health()
 
 
-@app.route('/health/basic', methods=['GET'], cors=True)
+@app.route('/health/basic', methods=['GET'], cors=True, **aux_spec.basic_health())
 def basic_health():
     return app.health_controller.basic_health()
 
 
-@app.route('/health/cached', methods=['GET'], cors=True)
+@app.route('/health/cached', methods=['GET'], cors=True, **aux_spec.cached_health())
 def cached_health():
     return app.health_controller.cached_health()
 
 
-@app.route('/health/fast', methods=['GET'], cors=True)
+@app.route('/health/fast', methods=['GET'], cors=True, **aux_spec.fast_health())
 def fast_health():
     return app.health_controller.fast_health()
 
 
-@app.route('/health/{keys}', methods=['GET'], cors=True)
+@app.route('/health/{keys}', methods=['GET'], cors=True, **aux_spec.custom_health())
 def health_by_key(keys: Optional[str] = None):
     return app.health_controller.custom_health(keys)
 
@@ -151,7 +158,35 @@ def update_health_cache(_event: chalice.app.CloudWatchEvent):
     app.health_controller.update_cache()
 
 
-@app.route('/{catalog}/{action}', methods=['POST'])
+@app.route('/{catalog}/{action}', methods=['POST'], method_spec={
+    'tags': ['Indexing'],
+    'summary': 'Notify the indexer to perform an action',
+    'consumes': [
+        'application/json'
+    ],
+    'parameters': [
+        params.path('catalog',
+                    schema.enum(*config.catalogs),
+                    description='The name of the catalog to notify.'),
+        params.path('action',
+                    schema.enum(*Action.__members__),
+                    description='Which action to perform.'),
+        params.body('notification',
+                    schema.object(additional_properties=True),
+                    description='Contents of the notification.')
+    ],
+    'responses': {
+        '200': {
+            'description': 'Notification was successfully queued for processing'
+        },
+        '400': {
+            'description': 'Notification was rejected due to malformed contents'
+        },
+        '401': {
+            'description': 'Request lacked a valid HMAC header'
+        }
+    }
+})
 def post_notification(catalog: CatalogName, action: str):
     """
     Receive a notification event and queue it for indexing or deletion.

src/azul/openapi/params.py

@@ -54,6 +54,10 @@ def query(name: str, type_: Union[TYPE, schema.optional], **kwargs: PrimitiveJSO
     return _make_param(name, in_='query', type_=type_, **kwargs)
 
 
+def body(name: str, type_: TYPE, **kwargs) -> JSON:
+    return _make_param(name, in_='body', type_=type_, **kwargs)
+
+
 def _make_param(name: str, in_: str, type_: Union[TYPE, schema.optional], **kwargs: PrimitiveJSON) -> JSON:
     is_optional = isinstance(type_, schema.optional)
     if is_optional: