Add Swagger UI docs endpoint at /jsonapi/docs

tvdeyen · tvdeyen · commit a02a4f22e95a · 2026-07-18T17:41:01.000+02:00
Serves a lightweight HTML page that loads Swagger UI from the CDN and
points it at the existing /jsonapi/openapi.json endpoint. No extra gem
dependencies required.

Signed-off-by: Thomas von Deyen &lt;thomas@vondeyen.com&gt;
diff --git a/app/controllers/alchemy/json_api/openapi_controller.rb b/app/controllers/alchemy/json_api/openapi_controller.rb
@@ -10,6 +10,11 @@ def show
         render json: spec
       end
 
+      def docs
+        @spec_url = alchemy_json_api.openapi_path(format: :json)
+        render layout: false
+      end
+
       private
 
       def spec
diff --git a/app/views/alchemy/json_api/openapi/docs.html.erb b/app/views/alchemy/json_api/openapi/docs.html.erb
@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>Alchemy JSON:API Documentation</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+    <style>html { box-sizing: border-box; } *, *::before, *::after { box-sizing: inherit; }</style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script>
+      SwaggerUIBundle({
+        url: <%== @spec_url.to_json %>,
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
+        layout: "BaseLayout"
+      });
+    </script>
+  </body>
+</html>
diff --git a/config/routes.rb b/config/routes.rb
@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 Alchemy::JsonApi::Engine.routes.draw do
-  get "openapi", to: "openapi#show", defaults: {format: :json}
+  get "openapi", to: "openapi#show", defaults: {format: :json}, as: :openapi
+  get "docs", to: "openapi#docs", constraints: ->(_r) { Rails.env.development? }
 
   resources :pages, only: [:index]
   get "pages/*path" => "pages#show", :as => :page
diff --git a/spec/requests/alchemy/json_api/openapi_spec.rb b/spec/requests/alchemy/json_api/openapi_spec.rb
@@ -16,4 +16,32 @@
       expect(document["paths"]).to include("/pages", "/pages/{path}", "/nodes")
     end
   end
+
+  describe "GET /alchemy/json_api/docs" do
+    context "in development environment" do
+      before do
+        allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new("development"))
+        Rails.application.reload_routes!
+      end
+
+      it "returns an HTML page with Swagger UI in development", :aggregate_failures do
+        get alchemy_json_api.docs_path
+
+        expect(response).to have_http_status(:ok)
+        expect(response.content_type).to include("text/html")
+        expect(response.body).to include("swagger-ui")
+        expect(response.body).to include(alchemy_json_api.openapi_path)
+      end
+
+      after do
+        allow(Rails).to receive(:env).and_call_original
+        Rails.application.reload_routes!
+      end
+    end
+
+    it "is not routable in non-development environments" do
+      get alchemy_json_api.docs_path
+      expect(response).to have_http_status(:not_found)
+    end
+  end
 end
