scalar_ruby 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 665e34004852e3c7508b7d672ce7222f1de09183a4549bff71f82144975e476c
-  data.tar.gz: 60d68fdb4072cc5dff56e25911270ce05828c7231b9f7cc49aa1b8cc66138100
+  metadata.gz: a21547938d1fb384cf1a97984c15eb33dd883d0f4c0e4e4a2bea9482d37215ce
+  data.tar.gz: df9316873f075b3a1b5e3e46734ac2a90d0febaa29a86d02ecdcd7b6c9231e6c
 SHA512:
-  metadata.gz: bb139b0a28acb3e42418370b36611a7eb7ea8c885f02c11c3fda2662b5424a71bb1f5be5c117173662c5ba45ae0dcf8b0ae05475964199335eb242323910718e
-  data.tar.gz: 0e27fe32e65004da16237aaa7a4300f5a005f61367fe4d8d0fa3028ec9e0d88d7c1d3d9eb438f5b84de8884cfdea0dd5957e5ce773905f2f8356f4edc6126d83
+  metadata.gz: d5b51185f6c4677087b0dc9529db5d0fa476354b2862cca2be6b2560b592d6ee696eaf6e65c2202e0d27c5e337ff7de3c224fc1bd2d5e10ecb118dc7a37f23a1
+  data.tar.gz: bc7f9f3c0acd9e159c97bf58770ed627f75847dc655941fc1e164c420a9b306a923313ef704ee82a34e1031230ca6775c608959e0a977eaa3f87c119e5ef47ac

data/README.md

@@ -1,7 +1,14 @@
+[![Gem Version](https://badge.fury.io/rb/scalar_ruby.svg)](https://badge.fury.io/rb/scalar_ruby)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/dmytroshevchuk/scalar_ruby/check.yml)](https://github.com/dmytroshevchuk/scalar_ruby/actions/workflows/check.yml)
+
 # Scalar API Reference for Ruby
 
 This gem simplifies the integration of [Scalar](https://scalar.com), a modern open-source developer experience platform for your APIs into Ruby applications.
 
+## Requirements
+
+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
 
 Add the gem to your application's Gemfile by executing in the terminal:
@@ -27,35 +34,43 @@ 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
 ```
 
 And that's it! More detailed information on other configuration options is in the section below.
 
+## Integrations
+
+You can use the built-in generator to set up the gem in [Ruby on Rails](https://rubyonrails.org) by running:
+
+```bash
+bin/rails generate scalar:install
+```
+
 ## Configuration
 
 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`.
 
@@ -63,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
 ```
 
-Below, you’ll find a complete list of configuration settings:
+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
+```
+
+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:
 
@@ -82,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
 ```
 
@@ -102,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/USAGE

@@ -0,0 +1,11 @@
+Description:
+  Installs Scalar, modern open-source developer experience platform for your APIs
+
+Example:
+  bin/rails generate scalar:install
+
+This will update:
+  config/routes.rb
+
+This will create:
+  config/initializers/scalar.rb

data/lib/generators/scalar/install/install_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Scalar
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Installs Scalar into a Rails app'
+
+      def introduction
+        say <<~INTRODUCTION
+
+          👋 Let's install Scalar into your Rails app!
+
+        INTRODUCTION
+      end
+
+      def update_routes
+        insert_into_file Rails.root.join('config/routes.rb'), after: 'Rails.application.routes.draw do' do
+          "\n  mount Scalar::UI, at: \"/docs\""
+        end
+      end
+
+      def create_initializer
+        template 'initializer.rb', 'config/initializers/scalar.rb'
+      end
+
+      def farewell
+        say <<~FAREWELL
+
+          We're done! Your can run "/docs" to observe a scalar API platform
+
+        FAREWELL
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+Scalar.setup do |config|
+  # 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"
+
+  # Set Scalar configuration (e.g. theme, single/multiple specifications or,
+  # document sources, etc.)
+  #
+  # config.scalar_configuration = {
+  #   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.0.0'
+  VERSION = '2.0.0'
 end

metadata

@@ -1,17 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: scalar_ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Dmytro Shevchuk
 - Serhii Ponomarov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description:
 email:
 - dmytro@hey.com
 - sergii.ponomarov@gmail.com
@@ -21,6 +19,9 @@ extra_rdoc_files: []
 files:
 - README.md
 - Rakefile
+- lib/generators/scalar/install/USAGE
+- lib/generators/scalar/install/install_generator.rb
+- lib/generators/scalar/install/templates/initializer.rb
 - lib/scalar/config.rb
 - lib/scalar/template.erb
 - lib/scalar/ui.rb
@@ -33,7 +34,6 @@ metadata:
   homepage_uri: https://github.com/dmytroshevchuk/scalar_ruby
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/dmytroshevchuk/scalar_ruby
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -41,15 +41,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.5
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A gem to automate using Scalar with Ruby apps
 test_files: []