Merge pull request #38 from tmeiczin/tjm/change-params

re-factor parameter names

Author: tmeiczin

example/__main__.py

@@ -38,7 +38,6 @@ def main():
     """Execute main method."""
     bind_address = "127.0.0.01"
     bind_port = 8000
-    api_url = None
     workers = 2
     parser = argparse.ArgumentParser()
     resource_path = os.path.abspath(os.path.dirname(sys.modules[__name__].__file__)) + "/resources"
@@ -49,7 +48,9 @@ def main():
         default=bind_address,
     )
     parser.add_argument("--port", help="Bind port to listen for requests", default=bind_port)
-    parser.add_argument("--api-url", help="API URL", default=api_url)
+    parser.add_argument("--ui-url", help="OpenAPI UI URL (ie Swagger index) default is address:port")
+    parser.add_argument("--docs", help="Docs", default="/docs")
+    parser.add_argument("--server", help="Additional server(s) usable in the API docs", nargs="*", action="append")
     parser.add_argument("--resource-path", help="Path to API resource modules", default=resource_path)
     parser.add_argument("--workers", help="Number of worker threads", default=workers)
     parser.add_argument("--config", help="Configuration file", default=None)
@@ -65,6 +66,8 @@ def main():
     auth = AuthMiddleware([basic_auth, cookie_auth], control=AccessResource(default_mode="deny"))
 
     args = parser.parse_args()
+
+    servers = [{"url": x, "description": ""} for x in args.server] if args.server else []
     middleware = [auth]
     if args.config:
         config = load_config(args.config)
@@ -91,11 +94,12 @@ def main():
     openapi = {
         "highlight": True,
         "sort": "alpha",
+        "ui_url": args.ui_url,
+        "servers": servers,
     }
 
     app = Application(
         resource_path=args.resource_path,
-        api_url=args.api_url,
         loglevel="info",
         accesslog=None,
         middleware=middleware,

src/reliqua/api.py

@@ -71,7 +71,8 @@ def __init__(
         openapi = openapi or {}
 
         openapi_path = openapi["path"]
-        self.url = openapi["api_url"]
+        self.url = openapi["ui_url"]
+        self.servers = openapi["servers"]
 
         self.openapi = openapi
         self.info = info
@@ -199,11 +200,11 @@ def _add_docs(self):
             sort=self.openapi["sort"],
             highlight=self.openapi["highlight"],
         )
-        openapi = OpenApi(**self.info, auth=self.auth)
+        openapi = OpenApi(**self.info, auth=self.auth, servers=self.servers)
         openapi.process_resources(self.resources)
         schema = openapi.schema()
-        print(f"adding static route {self.openapi['docs_endpoint']} {self.openapi['file_path']}")
+        print(f"adding static route {self.openapi['docs']} {self.openapi['file_path']}")
         self.add_static_route(self.openapi["static"], self.openapi["file_path"])
-        self.add_route(self.openapi["docs_endpoint"], swagger)
+        self.add_route(self.openapi["docs"], swagger)
         print(f"adding openapi file {self.openapi['spec']}")
         self.add_route(self.openapi["spec"], Docs(schema))

src/reliqua/app.py

@@ -23,12 +23,12 @@
 }
 
 OPENAPI_DEFAULTS = {
-    "api_url": None,  # API URL used by OpenAI UI (if different from bind, for example, behind a proxy)
-    "ui_url": None,  # OpenAPI UI index url
+    "ui_url": None,  # Swagger UI index URL (if different from bind, for example, behind a proxy))
     "highlight": True,  # Enable OpenAPI syntax highlighting
     "sort": "alpha",  # OpenAPI endpoint/tag sort order
     "path": "/openapi",  # OpenAPI endpoint path (JSON and static files)
-    "docs_endpoint": "/docs",  # Documentation endpoint
+    "docs": "/docs",  # Documentation endpoint
+    "servers": [],  # List of target API servers (default is bind address)
 }
 
 INFO_DEFAULTS = {
@@ -129,7 +129,11 @@ def __init__(
 
         # Trim slashes from proxy URL if specified; otherwise set default proxy URL
         bind = self.gunicorn_options["bind"]
-        openapi["api_url"] = openapi["api_url"].rstrip("/") if openapi["api_url"] else f"http://{bind}"
+        openapi["ui_url"] = openapi["ui_url"].rstrip("/") if openapi["ui_url"] else f"http://{bind}"
+
+        # Add default api server if none specified
+        if len(openapi["servers"]) == 0:
+            openapi["servers"] = [{"url": f"http://{bind}", "description": "Default server"}]
 
         self.application = Api(
             resource_path=resource_path,

src/reliqua/openapi.py

@@ -47,6 +47,7 @@ def camelcase(string):
     "dict": "object",
 }
 
+
 DEFAULT_RESPONSE = {
     "type": "object",
     "properties": {
@@ -59,6 +60,10 @@ def camelcase(string):
     },
 }
 
+
+BINARY_RESPONSE = {"type": "string", "format": "binary"}
+
+
 verbs = ["get", "patch", "put", "post", "delete"]
 
 
@@ -591,6 +596,7 @@ def __init__(
         contact_email="",
         auth=None,
         parser=None,
+        servers=None,
     ):
         """
         Create an OpenAPI class.
@@ -609,6 +615,7 @@ def __init__(
         :param str contact_url:    Software URL
         :param str contact_email:  Contact email
         :param Parser parser:      The docstring parser
+        :param list servers:       List of servers
         :return:
         """
         self.openapi = "3.1.0"
@@ -618,6 +625,7 @@ def __init__(
         self.summary = summary or ""
         self.terms = terms or ""
         self.auth = auth or []
+        self.servers = servers or []
 
         contact = Contact(name=contact_name, email=contact_email, url=contact_url)
         license = License(name=license, url=license_url)
@@ -633,6 +641,7 @@ def __init__(
         self.paths = {}
         self.component_schemas = {
             "default_response": DEFAULT_RESPONSE,
+            "binary": BINARY_RESPONSE,
         }
         self.parser = parser
 
@@ -682,4 +691,5 @@ def schema(self):
             "paths": self.paths,
             "components": self.components,
             "security": self.security_names,
+            "servers": self.servers,
         }