diff --git a/Gemfile.lock b/Gemfile.lock index 3b47f39..5b340de 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -10,20 +10,20 @@ 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) @@ -31,7 +31,7 @@ GEM 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 index a928988..d42a690 100644 --- a/README.md +++ b/README.md @@ -82,10 +82,26 @@ 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 @@ -93,7 +109,7 @@ Parameter | Description `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: @@ -101,7 +117,7 @@ Example of setting configuration options: # 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 index fcaff00..b8e0a7d 100644 --- a/lib/generators/scalar/install/templates/initializer.rb +++ b/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,11 +9,13 @@ # # 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 index 9983d5d..5865aee 100644 --- a/lib/scalar/config.rb +++ b/lib/scalar/config.rb @@ -10,7 +10,8 @@ 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, @@ -18,18 +19,25 @@ class Config :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 index 4e7d296..8217070 100644 --- 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 %> diff --git a/test/scalar/test_config.rb b/test/scalar/test_config.rb index 8cb1fe3..0422829 100644 --- 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 index c8c0def..b36c5a5 100644 --- 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 index 131ddc4..f97214e 100644 --- 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'