Merge pull request #512 from TeskaLabs/feature/swagger-2311

Improve on the Swagger doc
TeskaLabs · Jan 25, 2024 · 0791afa · 0791afa
2 parents 5dd09d7 + a133591
commit 0791afa
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 34 deletions.
diff --git a/asab/api/doc.py b/asab/api/doc.py
@@ -47,7 +47,7 @@ def __init__(self, api_service, app, web_container, config_section_name="asab:do
 		self.ServerUrls: str = asab.Config.get(config_section_name, "server_urls", fallback="/").strip().split("\n")
 
 
-	def build_swagger_documentation(self) -> dict:
+	def build_swagger_documentation(self, host) -> dict:
 		"""
 		Take a docstring of the class and a docstring of methods and merge them into Swagger data.
 		"""
@@ -65,7 +65,7 @@ def build_swagger_documentation(self) -> dict:
 				"version": self.get_version_from_manifest(),
 			},
 			"servers": [
-				{"url": url} for url in self.ServerUrls
+				{"url": "http://{}".format(host)}
 			],
 			"components": {
 				"securitySchemes": self.create_security_schemes()},
@@ -248,11 +248,13 @@ async def doc(self, request):
 		swagger_js_url: str = "https://unpkg.com/swagger-ui-dist@4/swagger-ui-bundle.js"
 		swagger_css_url: str = "https://unpkg.com/swagger-ui-dist@4/swagger-ui.css"
 
+		base_url = request.headers.get('Host')
+
 		doc_page = SWAGGER_DOC_PAGE.format(
 			title=self.App.__class__.__name__,
 			swagger_css_url=swagger_css_url,
 			swagger_js_url=swagger_js_url,
-			openapi_url="./asab/v1/openapi",
+			openapi_url="http://{}/asab/v1/openapi".format(base_url),
 		)
 
 		return aiohttp.web.Response(text=doc_page, content_type="text/html")
@@ -280,8 +282,11 @@ async def openapi(self, request):
 		url: https://swagger.io/specification/
 
 		"""
+
+		host = request.headers.get('Host')
+
 		return aiohttp.web.Response(
-			text=(yaml.dump(self.build_swagger_documentation(), sort_keys=False)),
+			text=(yaml.dump(self.build_swagger_documentation(host=host), sort_keys=False)),
 			content_type="text/yaml",
 		)
 

diff --git a/asab/api/doc_templates.py b/asab/api/doc_templates.py
@@ -79,31 +79,22 @@
 </html>"""
 
 SWAGGER_DOC_PAGE = """<!DOCTYPE html>
-<html lang="en">
-<head>
-	<meta charset="utf-8" />
-	<meta name="viewport" content="width=device-width, initial-scale=1" />
-	<link type="text/css" rel="stylesheet" href="{swagger_css_url}">
-	<title>{title} API Documentation</title>
-	<style>
-		code {{ tab-size: 4; }}
-		pre {{ tab-size: 4; }}
-	</style>
-</head>
-<body>
-<div id="swagger-ui"></div>
-<script src="{swagger_js_url}"></script>
-<script>
-window.onload = () => {{
-	window.ui = SwaggerUIBundle({{
-		url: '{openapi_url}',
-		dom_id: '#swagger-ui',
-		presets: [
-			SwaggerUIBundle.presets.apis,
-			SwaggerUIBundle.SwaggerUIStandalonePreset
-		]
-	}})
-}}
-</script>
-</body>
-</html>"""
+<html>
+	<head>
+		<title>API Reference {openapi_url}</title>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<style>
+			body {{
+				margin: 0;
+			}}
+		</style>
+	</head>
+	<body>
+		<script
+			id="api-reference"
+			data-url="{openapi_url}"></script>
+		<script src="https://www.unpkg.com/@scalar/api-reference"></script>
+	</body>
+</html>
+"""
diff --git a/asab/web/__init__.py b/asab/web/__init__.py
@@ -19,7 +19,7 @@ def __init__(self, app):
 		self.service = WebService(app, "asab.WebService")
 
 
-def create_web_server(app, section: str = "web", config: typing.Optional[dict] = None) -> aiohttp.web.UrlDispatcher:
+def create_web_server(app, section: str = "web", config: typing.Optional[dict] = None, api: bool = False) -> aiohttp.web.UrlDispatcher:
 	"""
 Build the web server with the specified configuration.
 
@@ -49,6 +49,13 @@ async def hello(self, request):
 	app.add_module(Module)
 	websvc = app.get_service("asab.WebService")
 	container = WebContainer(websvc, section, config=config)
+
+	if api:
+		# The DiscoverySession is functional only with ApiService initialized.
+		from ..api import ApiService
+		apisvc = ApiService(app)
+		apisvc.initialize_web(container)
+
 	return container.WebApp.router
 
 

diff --git a/examples/webserver.py b/examples/webserver.py
@@ -1,4 +1,6 @@
 #!/usr/bin/env python3
+
+import asab.api
 import asab.web.rest
 
 
@@ -14,7 +16,7 @@ def __init__(self):
 		super().__init__()
 
 		# Create the Web server
-		web = asab.web.create_web_server(self)
+		web = asab.web.create_web_server(self, api = True)
 
 		# Add a route to the handler method
 		web.add_get('/hello', self.hello)