Add swagger-ui docs and clean up swagger-ui options (#1739)

Contributes to #1531

connexion/apps/abstract.py

@@ -12,6 +12,7 @@
 from connexion.jsonifier import Jsonifier
 from connexion.middleware import ConnexionMiddleware, MiddlewarePosition, SpecMiddleware
 from connexion.middleware.lifespan import Lifespan
+from connexion.options import SwaggerUIOptions
 from connexion.resolver import Resolver
 from connexion.uri_parsing import AbstractURIParser
 
@@ -43,7 +44,7 @@ def __init__(
         resolver: t.Optional[t.Union[Resolver, t.Callable]] = None,
         resolver_error: t.Optional[int] = None,
         strict_validation: t.Optional[bool] = None,
-        swagger_ui_options: t.Optional[dict] = None,
+        swagger_ui_options: t.Optional[SwaggerUIOptions] = None,
         uri_parser_class: t.Optional[AbstractURIParser] = None,
         validate_responses: t.Optional[bool] = None,
         validator_map: t.Optional[dict] = None,
@@ -72,8 +73,8 @@ def __init__(
             start.
         :param strict_validation: When True, extra form or query parameters not defined in the
             specification result in a validation error. Defaults to False.
-        :param swagger_ui_options: A dict with configuration options for the swagger ui. See
-            :class:`options.ConnexionOptions`.
+        :param swagger_ui_options: Instance of :class:`options.ConnexionOptions` with
+            configuration options for the swagger ui.
         :param uri_parser_class: Class to use for uri parsing. See :mod:`uri_parsing`.
         :param validate_responses: Whether to validate responses against the specification. This has
             an impact on performance. Defaults to False.
@@ -128,7 +129,7 @@ def add_api(
         resolver: t.Optional[t.Union[Resolver, t.Callable]] = None,
         resolver_error: t.Optional[int] = None,
         strict_validation: t.Optional[bool] = None,
-        swagger_ui_options: t.Optional[dict] = None,
+        swagger_ui_options: t.Optional[SwaggerUIOptions] = None,
         uri_parser_class: t.Optional[AbstractURIParser] = None,
         validate_responses: t.Optional[bool] = None,
         validator_map: t.Optional[dict] = None,

connexion/apps/asynchronous.py

@@ -17,6 +17,7 @@
 from connexion.middleware.abstract import RoutedAPI, RoutedMiddleware
 from connexion.middleware.lifespan import Lifespan
 from connexion.operations import AbstractOperation
+from connexion.options import SwaggerUIOptions
 from connexion.resolver import Resolver
 from connexion.uri_parsing import AbstractURIParser
 
@@ -131,7 +132,7 @@ def __init__(
         resolver: t.Optional[t.Union[Resolver, t.Callable]] = None,
         resolver_error: t.Optional[int] = None,
         strict_validation: t.Optional[bool] = None,
-        swagger_ui_options: t.Optional[dict] = None,
+        swagger_ui_options: t.Optional[SwaggerUIOptions] = None,
         uri_parser_class: t.Optional[AbstractURIParser] = None,
         validate_responses: t.Optional[bool] = None,
         validator_map: t.Optional[dict] = None,
@@ -161,8 +162,8 @@ def __init__(
             start.
         :param strict_validation: When True, extra form or query parameters not defined in the
             specification result in a validation error. Defaults to False.
-        :param swagger_ui_options: A dict with configuration options for the swagger ui. See
-            :class:`options.ConnexionOptions`.
+        :param swagger_ui_options: Instance of :class:`options.ConnexionOptions` with
+            configuration options for the swagger ui.
         :param uri_parser_class: Class to use for uri parsing. See :mod:`uri_parsing`.
         :param validate_responses: Whether to validate responses against the specification. This has
             an impact on performance. Defaults to False.

connexion/apps/flask.py

@@ -20,6 +20,7 @@
 from connexion.middleware.abstract import AbstractRoutingAPI, SpecMiddleware
 from connexion.middleware.lifespan import Lifespan
 from connexion.operations import AbstractOperation
+from connexion.options import SwaggerUIOptions
 from connexion.problem import problem
 from connexion.resolver import Resolver
 from connexion.uri_parsing import AbstractURIParser
@@ -188,7 +189,7 @@ def __init__(
         resolver: t.Optional[t.Union[Resolver, t.Callable]] = None,
         resolver_error: t.Optional[int] = None,
         strict_validation: t.Optional[bool] = None,
-        swagger_ui_options: t.Optional[dict] = None,
+        swagger_ui_options: t.Optional[SwaggerUIOptions] = None,
         uri_parser_class: t.Optional[AbstractURIParser] = None,
         validate_responses: t.Optional[bool] = None,
         validator_map: t.Optional[dict] = None,
@@ -221,8 +222,8 @@ def __init__(
             start.
         :param strict_validation: When True, extra form or query parameters not defined in the
             specification result in a validation error. Defaults to False.
-        :param swagger_ui_options: A dict with configuration options for the swagger ui. See
-            :class:`options.ConnexionOptions`.
+        :param swagger_ui_options: Instance of :class:`options.ConnexionOptions` with
+            configuration options for the swagger ui.
         :param uri_parser_class: Class to use for uri parsing. See :mod:`uri_parsing`.
         :param validate_responses: Whether to validate responses against the specification. This has
             an impact on performance. Defaults to False.

connexion/cli.py

@@ -8,12 +8,16 @@
 from os import path
 
 import click
-import importlib_metadata
 from clickclick import AliasedGroup
 
 import connexion
 from connexion.mock import MockResolver
 
+try:
+    import importlib_metadata
+except ImportError:
+    import importlib.metadata as importlib_metadata  # type: ignore
+
 logger = logging.getLogger("connexion.cli")
 
 FLASK_APP = "flask"

connexion/middleware/main.py

@@ -21,6 +21,7 @@
 from connexion.middleware.routing import RoutingMiddleware
 from connexion.middleware.security import SecurityMiddleware
 from connexion.middleware.swagger_ui import SwaggerUIMiddleware
+from connexion.options import SwaggerUIOptions
 from connexion.resolver import Resolver
 from connexion.uri_parsing import AbstractURIParser
 from connexion.utils import inspect_function_arguments
@@ -51,7 +52,7 @@ class _Options:
     resolver_error: t.Optional[int] = None
     resolver_error_handler: t.Optional[t.Callable] = field(init=False)
     strict_validation: t.Optional[bool] = False
-    swagger_ui_options: t.Optional[dict] = None
+    swagger_ui_options: t.Optional[SwaggerUIOptions] = None
     uri_parser_class: t.Optional[AbstractURIParser] = None
     validate_responses: t.Optional[bool] = False
     validator_map: t.Optional[dict] = None
@@ -186,7 +187,7 @@ def __init__(
         resolver: t.Optional[t.Union[Resolver, t.Callable]] = None,
         resolver_error: t.Optional[int] = None,
         strict_validation: t.Optional[bool] = None,
-        swagger_ui_options: t.Optional[dict] = None,
+        swagger_ui_options: t.Optional[SwaggerUIOptions] = None,
         uri_parser_class: t.Optional[AbstractURIParser] = None,
         validate_responses: t.Optional[bool] = None,
         validator_map: t.Optional[dict] = None,
@@ -214,8 +215,8 @@ def __init__(
             start.
         :param strict_validation: When True, extra form or query parameters not defined in the
             specification result in a validation error. Defaults to False.
-        :param swagger_ui_options: A dict with configuration options for the swagger ui. See
-            :class:`options.ConnexionOptions`.
+        :param swagger_ui_options: Instance of :class:`options.ConnexionOptions` with
+            configuration options for the swagger ui.
         :param uri_parser_class: Class to use for uri parsing. See :mod:`uri_parsing`.
         :param validate_responses: Whether to validate responses against the specification. This has
             an impact on performance. Defaults to False.
@@ -338,7 +339,7 @@ def add_api(
         resolver: t.Optional[t.Union[Resolver, t.Callable]] = None,
         resolver_error: t.Optional[int] = None,
         strict_validation: t.Optional[bool] = None,
-        swagger_ui_options: t.Optional[dict] = None,
+        swagger_ui_options: t.Optional[SwaggerUIOptions] = None,
         uri_parser_class: t.Optional[AbstractURIParser] = None,
         validate_responses: t.Optional[bool] = None,
         validator_map: t.Optional[dict] = None,

connexion/middleware/swagger_ui.py

@@ -16,7 +16,7 @@
 from connexion.jsonifier import Jsonifier
 from connexion.middleware import SpecMiddleware
 from connexion.middleware.abstract import AbstractSpecAPI
-from connexion.options import SwaggerUIOptions
+from connexion.options import SwaggerUIConfig, SwaggerUIOptions
 from connexion.utils import yamldumper
 
 logger = logging.getLogger("connexion.middleware.swagger_ui")
@@ -30,25 +30,25 @@ def __init__(
         self,
         *args,
         default: ASGIApp,
-        swagger_ui_options: t.Optional[dict] = None,
+        swagger_ui_options: t.Optional[SwaggerUIOptions] = None,
         **kwargs
     ):
         super().__init__(*args, **kwargs)
 
         self.router = Router(default=default)
-        self.options = SwaggerUIOptions(
+        self.options = SwaggerUIConfig(
             swagger_ui_options, oas_version=self.specification.version
         )
 
         if self.options.openapi_spec_available:
             self.add_openapi_json()
             self.add_openapi_yaml()
 
-        if self.options.openapi_console_ui_available:
+        if self.options.swagger_ui_available:
             self.add_swagger_ui()
 
         self._templates = Jinja2Templates(
-            directory=str(self.options.openapi_console_ui_from_dir)
+            directory=str(self.options.swagger_ui_template_dir)
         )
 
     @staticmethod
@@ -121,7 +121,7 @@ def add_swagger_ui(self):
         """
         Adds swagger ui to {base_path}/ui/
         """
-        console_ui_path = self.options.openapi_console_ui_path.strip().rstrip("/")
+        console_ui_path = self.options.swagger_ui_path.strip().rstrip("/")
         logger.debug("Adding swagger-ui: %s%s/", self.base_path, console_ui_path)
 
         for path in (
@@ -132,7 +132,7 @@ def add_swagger_ui(self):
                 methods=["GET"], path=path, endpoint=self._get_swagger_ui_home
             )
 
-        if self.options.openapi_console_ui_config is not None:
+        if self.options.swagger_ui_config:
             self.router.add_route(
                 methods=["GET"],
                 path=console_ui_path + "/swagger-ui-config.json",
@@ -155,7 +155,7 @@ async def redirect(request):
         # serve index.html, so we add the redirect above.
         self.router.mount(
             path=console_ui_path,
-            app=StaticFiles(directory=str(self.options.openapi_console_ui_from_dir)),
+            app=StaticFiles(directory=str(self.options.swagger_ui_template_dir)),
             name="swagger_ui_static",
         )
 
@@ -164,9 +164,9 @@ async def _get_swagger_ui_home(self, req):
         template_variables = {
             "request": req,
             "openapi_spec_url": (base_path + self.options.openapi_spec_path),
-            **self.options.openapi_console_ui_index_template_variables,
+            **self.options.swagger_ui_template_arguments,
         }
-        if self.options.openapi_console_ui_config is not None:
+        if self.options.swagger_ui_config:
             template_variables["configUrl"] = "swagger-ui-config.json"
 
         return self._templates.TemplateResponse("index.j2", template_variables)
@@ -175,7 +175,7 @@ async def _get_swagger_ui_config(self, request):
         return StarletteResponse(
             status_code=200,
             media_type="application/json",
-            content=json.dumps(self.options.openapi_console_ui_config),
+            content=json.dumps(self.options.swagger_ui_config),
         )