Added optional Redoc UI

mako-framework · Jan 25, 2024 · 5b71aea · 5b71aea
1 parent a20bf0f
commit 5b71aea
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 8 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,15 @@
+### 2.2.1 <small>(2023-11-23)</small>
+
+#### New
+
+* Added optional Redoc UI.
+
+#### Changes
+
+* Changed the default documentation URL to `/openapi/docs`.
+
+--------------------------------------------------------
+
 ### 2.2.0 <small>(2023-11-23)</small>
 
 #### New

diff --git a/src/http/controllers/Documentation.php b/src/http/controllers/Documentation.php
@@ -56,6 +56,29 @@ public function openapi(Response $response): string
 		return file_get_contents($openApiSpecPath);
 	}
 
+	/**
+	 * Returns the Recoc UI.
+	 */
+	public function redoc(URLBuilder $uRLBuilder): string
+	{
+		$specUrl = $uRLBuilder->toRoute('mako:openapi:spec');
+
+		return <<<HTML
+		<!DOCTYPE html>
+		<html lang="en">
+		<html>
+			<head>
+				<meta charset="UTF-8">
+				<title>OpenApi - Redoc</title>
+			</head>
+			<body>
+				<redoc spec-url="$specUrl"></redoc>
+				<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
+			</body>
+		</html>
+		HTML;
+	}
+
 	/**
 	 * Returns the Swagger UI.
 	 */
@@ -70,7 +93,7 @@ public function swagger(URLBuilder $uRLBuilder): string
 		<html>
 			<head>
 				<meta charset="UTF-8">
-				<title>OpenApi</title>
+				<title>OpenApi - Swagger</title>
 				<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui.min.css">
 			</head>
 			<body>
@@ -81,10 +104,12 @@ public function swagger(URLBuilder $uRLBuilder): string
 					const SetServerPlugin = (swagger) => ({
 						rootInjects: {
 							setServer: (server) => {
-								const oldSpec = swagger.getState().toJSON().spec.json;
-								const servers = [{url: server}];
-								const newSpec = Object.assign({}, oldSpec, { servers });
-								return swagger.specActions.updateJsonSpec(newSpec);
+								const spec = swagger.getState().toJSON().spec.json;
+								if (!spec.servers) {
+									const servers = [{url: server, description: 'Current server'}].concat(spec.servers || []);
+									const newSpec = Object.assign({}, spec, { servers });
+									swagger.specActions.updateJsonSpec(newSpec);
+								}
 							}
 						}
 					});

diff --git a/src/http/routing/Registrar.php b/src/http/routing/Registrar.php
@@ -21,7 +21,7 @@ class Registrar
 	/**
 	 * Registers the routes.
 	 */
-	public static function register(Routes $routes, string $cachedRoutes, string $openApiSpec, ?string $specPath = '/openapi/spec', ?string $swaggerPath = '/openapi/swagger'): void
+	public static function register(Routes $routes, string $cachedRoutes, string $openApiSpec, ?string $specPath = '/openapi/spec', ?string $swaggerPath = '/openapi/docs', string $docType = 'swagger'): void
 	{
 		// Include the cached routes if they exist. Otherwise we'll generate them at runtime.
 
@@ -32,15 +32,15 @@ public static function register(Routes $routes, string $cachedRoutes, string $op
 			(new Runtime($routes))->generateFromYamlFile($openApiSpec);
 		}
 
-		// Register the spec and swagger routes
+		// Register the spec and documentation routes
 
 		if ($specPath !== null) {
 			Documentation::setOpenApiSpecPath($openApiSpec);
 
 			$routes->get($specPath, [Documentation::class, 'openapi'], 'mako:openapi:spec');
 
 			if ($swaggerPath !== null) {
-				$routes->get($swaggerPath, [Documentation::class, 'swagger'], 'mako:openapi:swagger');
+				$routes->get($swaggerPath, [Documentation::class, $docType], 'mako:openapi:docs');
 			}
 		}
 	}