dmytroshevchuk · dmytroshevchuk · Aug 11, 2025
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -10,28 +10,28 @@ GEM
     bundler-audit (0.9.2)
       bundler (>= 1.2.0, < 3)
       thor (~> 1.0)
-    json (2.13.0)
+    json (2.13.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     minitest (5.25.5)
     parallel (1.27.0)
-    parser (3.3.8.0)
+    parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
     prism (1.4.0)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.0)
-    regexp_parser (2.10.0)
-    rubocop (1.78.0)
+    regexp_parser (2.11.1)
+    rubocop (1.79.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.45.1, < 2.0)
+      rubocop-ast (>= 1.46.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
     rubocop-ast (1.46.0)
@@ -65,4 +65,4 @@ DEPENDENCIES
   scalar_ruby!
 
 BUNDLED WITH
-   2.5.21
+   2.7.1
diff --git a/README.md b/README.md
@@ -82,26 +82,42 @@ The default configuration can be changed using the `Scalar.setup` method in `con
 # config/initializers/scalar.rb
 
 Scalar.setup do |config|
- config.page_title = 'My awesome API!'
+  config.page_title = 'My awesome API!'
 end
 ```
 
+There are two ways to pass the API specification.
+
+First, the `config.specification` setting. By default, it's blank. Pass the URL to the API specification or the content in OpenAPI format, and the value will be embedded into the `api-reference` script.
+
+Also, you can set the `config.specification` to `:demo`, and the `@scalar/galaxy` will be used as a specification. It may come in handy if you want to try out the library.
+
+```ruby
+# config/initializers/scalar.rb
+
+Scalar.setup do |config|
+  config.specification = :demo
+end
+```
+
+The second way is to pass the specification through the `config.scalar_configuration` setting. It's helpful if you want to specify multiple configurations or documents. See [Multiple Configurations guide](https://guides.scalar.com/scalar/scalar-api-references/configuration#openapi-documents__multiple-configurations "docs") for examples.
+
 Below, you’ll find a complete list of configuration settings:
 
 Parameter                                  | Description                                             | Default
 -------------------------------------------|---------------------------------------------------------|------------------------
 `config.page_title`                        | Defines the page title displayed in the browser tab.    | API Reference
 `config.library_url`                       | Allows to set a specific version of Scalar. By default, it uses the latest version of Scalar, so users get the latest updates and bug fixes.   | https://cdn.jsdelivr.net/npm/@scalar/api-reference
 `config.scalar_configuration`              | Scalar has a rich set of configuration options if you want to change how it works and looks. A complete list of configuration options can be found [here](https://github.com/scalar/scalar/blob/main/documentation/configuration.md).   | {}
-`config.specification`                     | Allows users to pass their OpenAPI specification to Scalar. It can be a URL to specification or a string object in JSON or YAML format.    | https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml
+`config.specification`                     | Allows users to pass their OpenAPI specification to Scalar. It can be a URL to specification or a string object in JSON or YAML format.    | nil
 
 Example of setting configuration options:
 
 ```ruby
 # config/initializers/scalar.rb
 
 Scalar.setup do |config|
- config.scalar_configuration = { theme: 'purple' }
+  config.scalar_configuration = { theme: 'purple' }
 end
 ```
 

diff --git a/lib/generators/scalar/install/templates/initializer.rb b/lib/generators/scalar/install/templates/initializer.rb
@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
 Scalar.setup do |config|
-  # Specify the specific version of the Scalar. By default it uses the latest one
+  # Specify the version of the Scalar. By default, it uses the latest one
   #
   # config.library_url = "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
 
   # Add custom page title displayed in the browser tab
   #
   # config.page_title = "API Reference"
 
-  # Pass your API specification. It may be URL or file content in OpenAPI format
+  # Pass your API specification. It may be :demo, a URL or file content in the
+  # OpenAPI format.
   #
-  # config.specification = File.read(Rails.root.join("docs/openapi.yml"))
+  # config.specification = :demo
 
-  # Additional Scalar configuration (e.g. theme) can be set here
+  # Set additional Scalar configuration (e.g. theme, multiple specifications or,
+  # document sources, etc.)
   #
   # config.scalar_configuration = {
   #   theme: "purple"

diff --git a/lib/scalar/config.rb b/lib/scalar/config.rb
@@ -10,26 +10,34 @@ class Config
     DEFAULT_LIBRARY_URL = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'
     DEFAULT_PAGE_TITLE = 'API Reference'
     DEFAULT_SCALAR_CONFIGURATION = {}.freeze
-    DEFAULT_SPECIFICATION = 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml'
+
+    DEMO_SPECIFICATION = 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml'
 
     attr_accessor :library_url,
                   :page_title,
                   :scalar_configuration,
                   :specification
 
     def initialize
-      set_defaults!
+      set_defaults
     end
 
     def scalar_configuration_to_json
       JSON.dump(scalar_configuration)
     end
 
-    def set_defaults!
+    def set_defaults
       @library_url = DEFAULT_LIBRARY_URL
       @page_title = DEFAULT_PAGE_TITLE
       @scalar_configuration = DEFAULT_SCALAR_CONFIGURATION
-      @specification = DEFAULT_SPECIFICATION
+      @specification = nil
+    end
+
+    def embedded_specification
+      return if specification.nil?
+      return DEMO_SPECIFICATION if specification.to_sym == :demo
+
+      specification
     end
   end
 end
diff --git a/lib/scalar/template.erb b/lib/scalar/template.erb
@@ -12,7 +12,7 @@
       id="api-reference"
       data-configuration=<%= config.scalar_configuration_to_json %>
     >
-      <%= config.specification %>
+      <%= config.embedded_specification %>
     </script>
 
     <script src="<%= config.library_url %>"></script>

diff --git a/test/scalar/test_config.rb b/test/scalar/test_config.rb
@@ -5,7 +5,7 @@
 module Scalar
   class TestConfig < Minitest::Test
     def setup
-      Scalar::Config.instance.set_defaults!
+      Scalar::Config.instance.set_defaults
 
       @instance = Scalar::Config.instance
     end
@@ -41,11 +41,17 @@ def test_scalar_configuration_to_json_returns_serialized_configuration
     end
 
     def test_that_specification_accessor_is_available
-      assert_equal(Scalar::Config::DEFAULT_SPECIFICATION, @instance.specification)
+      assert_nil(@instance.specification)
 
       @instance.specification = 'https://scalar.io/api/reference'
 
       assert_equal('https://scalar.io/api/reference', @instance.specification)
     end
+
+    def test_embedded_specification_returns_scalat_galaxy_specification_when_set_to_demo
+      @instance.specification = :demo
+
+      assert_equal(Scalar::Config::DEMO_SPECIFICATION, @instance.embedded_specification)
+    end
   end
 end
diff --git a/test/scalar/test_ui.rb b/test/scalar/test_ui.rb
@@ -5,7 +5,8 @@
 module Scalar
   class TestUI < Minitest::Test
     def setup
-      Scalar::Config.instance.set_defaults!
+      Scalar::Config.instance.set_defaults
+      Scalar::Config.instance.specification = :demo
 
       @status, @headers, @body = Scalar::UI.call({})
     end

diff --git a/test/test_scalar.rb b/test/test_scalar.rb
@@ -6,16 +6,24 @@ class TestScalar < Minitest::Test
   def setup
     @config = Scalar::Config.instance
 
-    @config.set_defaults!
+    @config.set_defaults
   end
 
   def test_default_values
     assert_equal(Scalar::Config::DEFAULT_LIBRARY_URL, @config.library_url)
     assert_equal(Scalar::Config::DEFAULT_PAGE_TITLE, @config.page_title)
     assert_equal(Scalar::Config::DEFAULT_SCALAR_CONFIGURATION, @config.scalar_configuration)
-    assert_equal(Scalar::Config::DEFAULT_SPECIFICATION, @config.specification)
+    assert_nil(@config.specification)
   end
 
+  # def test_setting_demo_specification
+  #   assert_nil(@config.specification)
+
+  #   @config.set_demo_specification
+
+  #   assert_equal(Scalar::Config::DEMO_SPECIFICATION, @config.specification)
+  # end
+
   def test_setup_allows_to_change_config
     Scalar.setup do |config|
       config.library_url = 'https://scalar.io/latest'