scalar_ruby 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebbb3b25b5e211a1aba05134d5f54aee9117073edf95f14c55dadd34c26a5141
-  data.tar.gz: d7918de252e40550258ad63b169c9fd6b8be93531390d54950c98f1dd0ca7bc7
+  metadata.gz: a21547938d1fb384cf1a97984c15eb33dd883d0f4c0e4e4a2bea9482d37215ce
+  data.tar.gz: df9316873f075b3a1b5e3e46734ac2a90d0febaa29a86d02ecdcd7b6c9231e6c
 SHA512:
-  metadata.gz: f6f20de57d3558a21630d3f8937ceb3d6863269189c77c75248b756868e2ab903dc6fdc30da9482c6a6e6db690e551b3e49b703ccbc5919bd1e6a3f7a2148472
-  data.tar.gz: 4f28e02faa358651f1aad4fc4f9908086f585d4bf2df05cf3081b13876a307173c91d795af7058755a54d0eb545a3a81c060c19889def3c158b04e3c76ae72b9
+  metadata.gz: d5b51185f6c4677087b0dc9529db5d0fa476354b2862cca2be6b2560b592d6ee696eaf6e65c2202e0d27c5e337ff7de3c224fc1bd2d5e10ecb118dc7a37f23a1
+  data.tar.gz: bc7f9f3c0acd9e159c97bf58770ed627f75847dc655941fc1e164c420a9b306a923313ef704ee82a34e1031230ca6775c608959e0a977eaa3f87c119e5ef47ac

data/README.md

@@ -7,11 +7,7 @@ This gem simplifies the integration of [Scalar](https://scalar.com), a modern op
 
 ## Requirements
 
-This gem is tested and supported on the following Ruby versions:
-
-- Ruby 3.0, 3.1, 3.2, 3.3
-
-Other Ruby versions might work but are not officially supported.
+This gem is tested and supported on the Ruby 2.7, 3.0, 3.1, 3.2, 3.3, and 3.4. Other Ruby versions might work but are not officially supported.
 
 ## Installation
 
@@ -38,25 +34,25 @@ end
 
 Restart the Rails server, and hit `localhost:3000/docs`. You'll see the default view of the Scalar API reference. It uses the `@scalar/galaxy` OpenAPI reference so that you will have something to play with immediately.
 
-Then, if you want to use your OpenAPI specification, you need to re-configure the Scalar.
+Then, if you want to use your OpenAPI specification, you need to re-configure Scalar.
 
-First, create an initializer, say `config/initializers/scalar.rb`. Then, set the desired specification as `config.specification` using the `Scalar.setup` method:
+First, create an initializer, say `config/initializers/scalar.rb`. Then, set the desired specification URL via the `config.configuration` setting using the `Scalar.setup` method:
 
 ```ruby
 # config/initializers/scalar.rb
 
 Scalar.setup do |config|
-  config.specification = File.read(Rails.root.join('docs/openapi.yml'))
+  config.configuration = { url: 'https://example.com/openapi.json' }
 end
 ```
 
-Also, you can pass a URL to the specification:
+Or embed the file content directly:
 
 ```ruby
 # config/initializers/scalar.rb
 
 Scalar.setup do |config|
-  config.specification = "#{ActionMailer::Base.default_url_options[:host]/openapi.json}"
+  config.configuration = { content: File.read(Rails.root.join('docs/openapi.yml')) }
 end
 ```
 
@@ -64,9 +60,9 @@ And that's it! More detailed information on other configuration options is in th
 
 ## Integrations
 
-You can use in-build generator to setup gem into [Ruby in Rails](https://rubyonrails.org) framework by running:
+You can use the built-in generator to set up the gem in [Ruby on Rails](https://rubyonrails.org) by running:
 
-```ruby
+```bash
 bin/rails generate scalar:install
 ```
 
@@ -74,7 +70,7 @@ bin/rails generate scalar:install
 
 Once mounted to your application, the library requires no further configuration. You can immediately start playing with the provided API reference example.
 
-Having default configurations set may be an excellent way to validate whether the Scalar fits your project. However, most users would love to utilize their specifications and be able to alter settings.
+Having default configurations set may be an excellent way to validate whether Scalar fits your project. However, most users would love to utilize their specifications and adjust settings.
 
 The default configuration can be changed using the `Scalar.setup` method in `config/initializers/scalar.rb`.
 
@@ -82,18 +78,97 @@ 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
+```
+
+Use the `config.configuration` setting to pass your API specification and customize Scalar's appearance. The value is a hash passed directly to the Scalar JavaScript library and supports all of Scalar's native configuration options.
+
+Pass a URL to your specification:
+
+```ruby
+# config/initializers/scalar.rb
+
+Scalar.setup do |config|
+  config.configuration = { url: 'https://example.com/openapi.json' }
+end
+```
+
+Or embed the file content:
+
+```ruby
+# config/initializers/scalar.rb
+
+Scalar.setup do |config|
+  config.configuration = { content: File.read(Rails.root.join('docs/openapi.yml')) }
+end
+```
+
+You can also set `config.configuration` to `:demo`, and the `@scalar/galaxy` spec will be used. It may come in handy if you want to try out the library.
+
+```ruby
+# config/initializers/scalar.rb
+
+Scalar.setup do |config|
+  config.configuration = :demo
+end
+```
+
+### Multiple API Documents
+
+To display multiple OpenAPI documents, use the `sources` array. The first entry is shown by default; add `default: true` to any source to override that.
+
+```ruby
+# config/initializers/scalar.rb
+
+Scalar.setup do |config|
+  config.configuration = {
+    sources: [
+      { title: 'Public API', url: '/openapi/public.json' },
+      { title: 'Internal API', url: '/openapi/internal.json', default: true },
+      { title: 'Legacy API', content: File.read(Rails.root.join('docs/legacy.yml')) }
+    ]
+  }
+end
+```
+
+You can also apply distinct settings per document by passing an array of configuration objects instead of a single hash:
+
+```ruby
+# config/initializers/scalar.rb
+
+Scalar.setup do |config|
+  config.configuration = [
+    {
+      title: 'Public API',
+      url: '/openapi/public.json',
+      theme: 'purple'
+    },
+    {
+      title: 'Internal API',
+      url: '/openapi/internal.json',
+      theme: 'bluePlanet',
+      default: true
+    }
+  ]
 end
 ```
 
-Below, you’ll find a complete list of configuration settings:
+Each source accepts:
+
+- `url` — absolute or relative URL to the OpenAPI document
+- `content` — inline JSON or YAML string
+- `title` — display name shown in the UI (auto-generated if omitted)
+- `slug` — URL identifier (auto-generated from title if omitted)
+- `default` — set to `true` to make this the initially displayed document
+
+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
+Parameter                     | Description                                                                                                                                                                                           | Default
+------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------
+`config.page_title`           | Defines the page title displayed in the browser tab.                                                                                                                                                  | API Reference
+`config.library_url`          | Allows setting a specific version of Scalar. By default, it uses the latest version, so users get the latest updates and bug fixes.                                                                   | https://cdn.jsdelivr.net/npm/@scalar/api-reference
+`config.configuration`        | A hash passed directly to the Scalar JavaScript library. Accepts all [Scalar configuration options](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) (e.g. `url`, `content`, `sources`, `theme`). Set to `:demo` to use the `@scalar/galaxy` demo spec. | `{}`
 
 Example of setting configuration options:
 
@@ -101,7 +176,10 @@ Example of setting configuration options:
 # config/initializers/scalar.rb
 
 Scalar.setup do |config|
- config.scalar_configuration = { theme: 'purple' }
+  config.configuration = {
+    theme: 'purple',
+    url: 'https://example.com/openapi.json'
+  }
 end
 ```
 
@@ -121,4 +199,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Scalar::Ruby project’s codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/dmytroshevchuk/scalar_ruby/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Scalar::Ruby project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/dmytroshevchuk/scalar_ruby/blob/master/CODE_OF_CONDUCT.md).

data/lib/generators/scalar/install/templates/initializer.rb

@@ -1,7 +1,7 @@
 # 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"
 
@@ -9,13 +9,15 @@ Scalar.setup do |config|
   #
   # config.page_title = "API Reference"
 
-  # Pass your API specification. It may be URL or file content in OpenAPI format
-  #
-  # config.specification = File.read(Rails.root.join("docs/openapi.yml"))
-
-  # Additional Scalar configuration (e.g. theme) can be set here
+  # Set Scalar configuration (e.g. theme, single/multiple specifications or,
+  # document sources, etc.)
   #
   # config.scalar_configuration = {
-  #   theme: "purple"
+  #   theme: "purple",
+  #   url: '...'
   # }
+  #
+  # To enable demo mode, uncomment the configuration below
+  #
+  # config.configuration = :demo
 end

data/lib/scalar/config.rb

@@ -9,27 +9,30 @@ module Scalar
 
     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'
+    DEFAULT_CONFIGURATION = {}.freeze
 
-    attr_accessor :library_url,
-                  :page_title,
-                  :scalar_configuration,
-                  :specification
+    DEMO_CONFIGURATION = {
+      url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml'
+    }.freeze
+
+    attr_accessor :configuration,
+                  :library_url,
+                  :page_title
 
     def initialize
-      set_defaults!
+      set_defaults
     end
 
-    def scalar_configuration_to_json
-      JSON.dump(scalar_configuration)
+    def configuration_to_json
+      return JSON.dump(DEMO_CONFIGURATION) if configuration == :demo
+
+      JSON.dump(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
+      @configuration = DEFAULT_CONFIGURATION
     end
   end
 end

data/lib/scalar/template.erb

@@ -8,13 +8,15 @@
   </head>
 
   <body>
-    <script
-      id="api-reference"
-      data-configuration=<%= config.scalar_configuration_to_json %>
-    >
-      <%= config.specification %>
-    </script>
+    <div id="app"></div>
 
     <script src="<%= config.library_url %>"></script>
+
+    <script>
+      Scalar.createApiReference(
+        '#app',
+        <%= config.configuration_to_json %>
+      )
+    </script>
   </body>
 </html>

data/lib/scalar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Scalar
-  VERSION = '1.1.0'
+  VERSION = '2.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scalar_ruby
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Dmytro Shevchuk
 - Serhii Ponomarov
 bindir: bin
 cert_chain: []
-date: 2025-02-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 email:
 - dmytro@hey.com
@@ -41,14 +41,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A gem to automate using Scalar with Ruby apps
 test_files: []