explicit 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46f92f599374b50a6ff4dcf044fadac51b9bf12d8f7c18b3f9bd1b39124be855
-  data.tar.gz: a9ec574ef2a8a6f3b0892994037fb7c19522af6afcaf4583933b8774b3ea2321
+  metadata.gz: 6d45270c6ac48802f9d370fb8afe70ec879f761499f589b5a875671161fbebaf
+  data.tar.gz: 2f2f57d5147f9f2a676c98727c63de82f7ed61477ad4d3b7bd0399ba4ea27c67
 SHA512:
-  metadata.gz: dafc5889a7c3a33a772f9c3eac434e24ce7424e1cdd0e9c8f24f859fa6a3f5143fd631546f40d7705e69a14b68b75cc7314c1420bdadda791ca57eb6f132dc5d
-  data.tar.gz: 9a03258778b8b0b7fd0b928c7414c8599f2d6e324dcd45b8284c8f6dc89cf4dce027942201f9c03237c24c96df3e7a124e798e8a30de38f9520b82cd11b0a87d
+  metadata.gz: e91a474e286da7b34fa36de63fa9885e1c89b765a4cf3aa2a0d9de8b936841247014f2ae6b326bc093cecb94fb05ae2cfc3824fe61f1be159554d98ac7df7d36
+  data.tar.gz: 40ab134356ea61d933c81379aa84977c70cb3d00cebfc3b62d1e3e26e6b698ba8f19993a22900ed6be07ec8e356272812de5a84bc87184014a29a226d055367b

data/README.md

@@ -28,6 +28,7 @@ documented types at runtime.
    - [Description](#description)
    - [Enum](#enum)
    - [File](#file)
+   - [Float](#float)
    - [Hash](#hash)
    - [Integer](#integer)
    - [Literal](#literal)
@@ -141,6 +142,9 @@ request instead of `Explicit::Request`. For example:
 
 ```ruby
 AuthenticatedRequest = Explicit::Request.new do
+  base_url "https://my-app.com"
+  base_path "/api/v1"
+
   header "Authorization", [:string, format: /Bearer [a-zA-Z0-9]{20}/]
 
   response 403, { error: "unauthorized" }
@@ -255,6 +259,8 @@ documentation for your API. The following methods are available:
 
 - `page_title(text)` - Sets the web page title.
 - `company_logo_url(url)` - Shows the company logo in the navigation menu.
+  The url can also be a lambda that returns the url, useful for referencing
+  assets at runtime.
 - `favicon_url(url)` - Adds a favicon to the web page.
 - `version(semver)` - Sets the version of the API. Default: "1.0"
 - `section(name, &block)` - Adds a section to the navigation menu.
@@ -548,6 +554,18 @@ match value_type. If you are expecting a hash with a specific set of keys use a
 
 Value must be an uploaded file using "multipart/form-data" encoding.
 
+### Float
+
+```ruby
+:float
+[:float, negative: false]
+[:float, positive: false]
+[:float, min: 0] # inclusive
+[:float, max: 10] # inclusive
+```
+
+Float encoded string alues such as "0.5" or "500.01" are automatically converted to `Float`.
+
 ### Integer
 
 ```ruby
@@ -559,7 +577,7 @@ Value must be an uploaded file using "multipart/form-data" encoding.
 ```
 
 Integer encoded string values such as "10" or "-2" are automatically converted
-to integer.
+to `Integer`.
 
 ### Literal
 

data/app/views/explicit/documentation/type/_float.html.erb

@@ -0,0 +1,25 @@
+<%= type_constraints do %>
+  <% if type.min.present? %>
+    <%= type_constraint "min", type.min %>
+  <% end %>
+
+  <% if type.max.present? %>
+    <%= type_constraint "max", type.max %>
+  <% end %>
+
+  <% if type.negative == false %>
+    <%= type_constraint "not", "negative" %>
+  <% end %>
+
+  <% if type.negative == true %>
+    <%= type_constraint "only", "negative" %>
+  <% end %>
+
+  <% if type.positive == false %>
+    <%= type_constraint "not", "positive" %>
+  <% end %>
+
+  <% if type.positive == true %>
+    <%= type_constraint "only", "positive" %>
+  <% end %>
+<% end %>

data/config/locales/en.yml

@@ -34,11 +34,14 @@ en:
       file: "must be a file"
       file_max_size: "must be smaller than %{max_size}"
       file_content_type: "file content type must be one of: %{allowed_content_types}"
+      float: "must be a number"
       integer: "must be an integer"
       min: "must be at least %{min}"
       max: "must be at most %{max}"
       not_negative: "must not be negative"
+      only_negative: "must be negative"
       not_positive: "must not be positive"
+      only_positive: "must be positive"
       literal: "must be %{value}"
       one_of_separator: "OR"
       string: "must be a string"
@@ -61,9 +64,9 @@ en:
       file_max_size: "* Max size: %{max_size}"
       file_content_types: "* Content types: %{content_types}"
       hash_not_empty: "* Must have at least one value"
-      integer_not_positive: "* Must not be positive"
-      integer_only_positive: "* Must be positive"
-      integer_not_negative: "* Must not be negative"
-      integer_only_negative: "* Must be negative"
+      number_not_positive: "* Must not be positive"
+      number_only_positive: "* Must be positive"
+      number_not_negative: "* Must not be negative"
+      number_only_negative: "* Must be negative"
       string_not_empty: "* Must not be empty"
       string_downcase: "* Case insensitive"

data/lib/explicit/documentation/builder.rb

@@ -59,6 +59,7 @@ module Explicit::Documentation
 
     def merge_request_examples_from_file!
       return if !Explicit.configuration.request_examples_file_path
+      return if !::File.exist?(Explicit.configuration.request_examples_file_path)
 
       encoded = ::File.read(Explicit.configuration.request_examples_file_path)
 

data/lib/explicit/documentation/output/swagger.rb

@@ -31,7 +31,7 @@ module Explicit::Documentation::Output
     def call(request)
       @swagger_document ||= swagger_document
 
-      [200, {"Content-Type" => "application/json"}, [@swagger_document.to_json]]
+      [ 200, { "Content-Type" => "application/json" }, [ @swagger_document.to_json ] ]
     end
 
     def inspect
@@ -43,7 +43,7 @@ module Explicit::Documentation::Output
         base_urls = builder.requests.map(&:get_base_url).uniq
         base_paths = builder.requests.map(&:get_base_path).uniq
 
-        if !base_urls.one?
+        if !base_urls.compact_blank.empty? && !base_urls.one?
           raise InconsistentBaseURLError.new <<~TXT
             There are requests with different base URLs in the same documentation,
             which is not supported by Swagger.
@@ -56,7 +56,7 @@ module Explicit::Documentation::Output
           TXT
         end
 
-        if !base_paths.one?
+        if !base_paths.compact_blank.empty? && !base_paths.one?
           raise InconsistentBasePathError.new <<~TXT
             There are requests with different base paths in the same documentation,
             which is not supported by Swagger.
@@ -69,7 +69,7 @@ module Explicit::Documentation::Output
           TXT
         end
 
-        base_urls.first + base_paths.first
+        (base_urls.first || "") + (base_paths.first || "")
       end
 
       def build_tags_from_sections
@@ -87,7 +87,7 @@ module Explicit::Documentation::Output
             route = request.routes.first
 
             paths[route.path_with_curly_syntax][route.method.to_s] = {
-              tags: [section.name],
+              tags: [ section.name ],
               summary: request.get_title,
               description: request.get_description,
               parameters: build_parameters(request),
@@ -132,7 +132,7 @@ module Explicit::Documentation::Output
 
         return nil if body_params_type.attributes.empty?
 
-        examples = 
+        examples =
           request.examples
             .flat_map { |_, examples| examples }
             .filter_map do |example|
@@ -141,7 +141,7 @@ module Explicit::Documentation::Output
               in [:error, _] then nil
               end
             end
-            .map.with_index { |example, index| [index, { value: example }] }
+            .map.with_index { |example, index| [ index, { value: example } ] }
             .to_h
 
         {
@@ -160,7 +160,7 @@ module Explicit::Documentation::Output
 
         request.responses.each do |status, _|
           examples = request.examples[status].map.with_index do |example, index|
-            [index.to_s, { value: example.response.data }]
+            [ index.to_s, { value: example.response.data } ]
           end.to_h
 
           responses[status] = {

data/lib/explicit/documentation/output/webpage.rb

@@ -19,15 +19,17 @@ module Explicit::Documentation::Output
     end
 
     private
+      Eval = ->(value) { value.respond_to?(:call) ? value.call : value }
+
       def render_documentation_page
         Explicit::ApplicationController.render(
           partial: "explicit/documentation/page",
           locals: {
             url_helpers: @builder.rails_engine.routes.url_helpers,
-            page_title: builder.get_page_title,
-            company_logo_url: builder.get_company_logo_url,
-            favicon_url: builder.get_favicon_url,
-            version: builder.get_version,
+            page_title: Eval[builder.get_page_title],
+            company_logo_url: Eval[builder.get_company_logo_url],
+            favicon_url: Eval[builder.get_favicon_url],
+            version: Eval[builder.get_version],
             sections: builder.sections,
           }
         )

data/lib/explicit/test_helper.rb

@@ -50,9 +50,13 @@ module Explicit::TestHelper
     end
 
     method = route.method
+    path = (request.get_base_path || "") + route.replace_path_params(params)
 
-    path = (request.get_base_path || "") + route.path
-    path = path.gsub(/:(\w+)/) { params.delete($1.to_sym).to_s }
+    if missing_path_param?(route, params)
+      raise <<~DESC
+        The request #{route} needs the following path parameters: #{route.params.join(", ")}
+      DESC
+    end
 
     process(method, path, params:, headers:)
 
@@ -90,6 +94,10 @@ module Explicit::TestHelper
     response
   end
 
+  def missing_path_param?(route, params)
+    route.params.any? { params.fetch(_1, nil).nil? }
+  end
+
   def ensure_response_matches_documented_type!(request, response)
     responses_type = request.responses_type(status: response.status)
 

data/lib/explicit/type/date.rb

@@ -11,7 +11,7 @@ class Explicit::Type::Date < Explicit::Type
   end
 
   def validate(value)
-    return [:ok, value] if value.is_a?(::Date)
+    return [ :ok, value ] if value.is_a?(::Date)
     return error_i18n("string") if !value.is_a?(::String)
 
     date = ::Date.parse(value, false)
@@ -32,7 +32,7 @@ class Explicit::Type::Date < Explicit::Type
       end
     end
 
-    [:ok, date]
+    [ :ok, date ]
   rescue ::Date::Error
     error_i18n("date_format")
   end
@@ -53,14 +53,14 @@ class Explicit::Type::Date < Explicit::Type
 
   concerning :Swagger do
     def swagger_schema
-      {
+      merge_base_swagger_schema({
         type: "string",
         pattern: /\d{4}-\d{2}-\d{2}/.inspect[1..-2],
         format: "date",
         description_topics: [
           swagger_i18n("date_format")
         ]
-      }
+      })
     end
   end
 end

data/lib/explicit/type/float.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+class Explicit::Type::Float < Explicit::Type
+  attr_reader :min, :max, :negative, :positive
+
+  def initialize(min: nil, max: nil, negative: nil, positive: nil)
+    @min = min
+    @max = max
+    @negative = negative
+    @positive = positive
+  end
+
+  ParseFromString = ->(value) do
+    Float(value)
+  rescue ::ArgumentError
+    nil
+  end
+
+  def validate(value)
+    value =
+      if value.is_a?(::Integer) || value.is_a?(::Float) || value.is_a?(::BigDecimal)
+        value
+      elsif value.is_a?(::String)
+        ParseFromString[value]
+      else
+        nil
+      end
+
+    return error_i18n("float") if value.nil?
+
+    if min && value < min
+      return error_i18n("min", min:)
+    end
+
+    if max && value > max
+      return error_i18n("max", max:)
+    end
+
+    if negative == false && value < 0
+      return error_i18n("not_negative")
+    end
+
+    if negative == true && value >= 0
+      return error_i18n("only_negative")
+    end
+
+    if positive == false && value > 0
+      return error_i18n("not_positive")
+    end
+
+    if positive == true && value <= 0
+      return error_i18n("only_positive")
+    end
+
+    [ :ok, value ]
+  end
+
+  concerning :Webpage do
+    def summary
+      "float"
+    end
+
+    def partial
+      "explicit/documentation/type/float"
+    end
+
+    def has_details?
+      min.present? || max.present? || !negative.nil? || !positive.nil?
+    end
+  end
+
+  concerning :Swagger do
+    def swagger_schema
+      merge_base_swagger_schema({
+        type: "number",
+        minimum: min,
+        maximum: max,
+        description_topics: [
+          positive == false ? swagger_i18n("number_not_positive") : nil,
+          positive == true ? swagger_i18n("number_only_positive") : nil,
+          negative == false ? swagger_i18n("number_not_negative") : nil,
+          negative == true ? swagger_i18n("number_only_negative") : nil
+        ]
+      })
+    end
+  end
+end

data/lib/explicit/type/integer.rb

@@ -40,11 +40,19 @@ class Explicit::Type::Integer < Explicit::Type
       return error_i18n("not_negative")
     end
 
+    if negative == true && value >= 0
+      return error_i18n("only_negative")
+    end
+
     if positive == false && value > 0
       return error_i18n("not_positive")
     end
 
-    [:ok, value]
+    if positive == true && value <= 0
+      return error_i18n("only_positive")
+    end
+
+    [ :ok, value ]
   end
 
   concerning :Webpage do
@@ -68,10 +76,10 @@ class Explicit::Type::Integer < Explicit::Type
         minimum: min,
         maximum: max,
         description_topics: [
-          positive == false ? swagger_i18n("integer_not_positive") : nil,
-          positive == true ? swagger_i18n("integer_only_positive") : nil,
-          negative == false ? swagger_i18n("integer_not_negative") : nil,
-          negative == true ? swagger_i18n("integer_only_negative") : nil
+          positive == false ? swagger_i18n("number_not_positive") : nil,
+          positive == true ? swagger_i18n("number_only_positive") : nil,
+          negative == false ? swagger_i18n("number_not_negative") : nil,
+          negative == true ? swagger_i18n("number_only_negative") : nil
         ]
       })
     end

data/lib/explicit/type/one_of.rb

@@ -27,28 +27,35 @@ class Explicit::Type::OneOf < Explicit::Type
     @subtypes.each do |subtype|
       case subtype.validate(value)
       in [:ok, validated_value]
-        return [:ok, validated_value]
+        return [ :ok, validated_value ]
       in [:error, err]
         errors << err
       end
     end
 
     if (err = guess_error_for_intended_subtype_via_matching_literal(value:, errors:))
-      return [:error, err]
+      return [ :error, err ]
     end
 
     if (err = guess_error_for_intended_subtype_via_matching_keys(value:, errors:))
-      return [:error, err]
+      return [ :error, err ]
     end
 
+    separator =
+      if ::I18n.exists?("explicit.errors.one_of_separator")
+        ::I18n.t("explicit.errors.one_of_separator")
+      else
+        ::I18n.t("explicit.errors.one_of_separator", locale: :en)
+      end
+
     error =
       if @subtypes_are_records
-        errors.map { ::JSON.pretty_generate(_1) }.join("\n\n#{ ::I18n.t('explicit.errors.one_of_separator')}\n\n")
+        errors.map { ::JSON.pretty_generate(_1) }.join("\n\n#{separator}\n\n")
       else
-        errors.join(" #{I18n.t('explicit.errors.one_of_separator')} ")
+        errors.join(" #{separator} ")
       end
 
-    [:error, error]
+    [ :error, error ]
   end
 
   def guess_error_for_intended_subtype_via_matching_literal(value:, errors:)
@@ -101,4 +108,4 @@ class Explicit::Type::OneOf < Explicit::Type
       { oneOf: subtypes.map(&:swagger_schema) }
     end
   end
-end
+end

data/lib/explicit/type.rb

@@ -59,6 +59,11 @@ class Explicit::Type
     in [:file, options]
       Explicit::Type::File.new(**options)
 
+    in :float
+      Explicit::Type::Float.new
+    in [:float, options]
+      Explicit::Type::Float.new(**options)
+
     in :integer
       Explicit::Type::Integer.new
     in [:integer, options]
@@ -109,13 +114,24 @@ class Explicit::Type
   def error_i18n(name, context = {})
     key = "explicit.errors.#{name}"
 
-    [:error, ::I18n.t(key, **context)]
+    translation =
+      if ::I18n.exists?(key)
+        ::I18n.t(key, **context)
+      else
+        ::I18n.t(key, **context.merge(locale: :en))
+      end
+
+    [ :error, translation ]
   end
 
   def swagger_i18n(name, context = {})
     key = "explicit.swagger.#{name}"
 
-    ::I18n.t(key, **context)
+    if ::I18n.exists?(key)
+      ::I18n.t(key, **context)
+    else
+      ::I18n.t(key, **context.merge(locale: :en))
+    end
   end
 
   def merge_base_swagger_schema(attributes)
@@ -144,4 +160,4 @@ class Explicit::Type
 
     base_attributes.merge(attributes).compact_blank
   end
-end
+end

data/lib/explicit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Explicit
-  VERSION = "0.2.6"
+  VERSION = "0.2.8"
 end

data/lib/explicit.rb

@@ -35,6 +35,7 @@ require "explicit/type/date_time_unix_epoch"
 require "explicit/type/date"
 require "explicit/type/enum"
 require "explicit/type/file"
+require "explicit/type/float"
 require "explicit/type/hash"
 require "explicit/type/integer"
 require "explicit/type/literal"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: explicit
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - Luiz Vasconcellos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-01-31 00:00:00.000000000 Z
+date: 2025-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -66,6 +66,7 @@ files:
 - app/views/explicit/documentation/type/_date_time_unix_epoch.html.erb
 - app/views/explicit/documentation/type/_enum.html.erb
 - app/views/explicit/documentation/type/_file.html.erb
+- app/views/explicit/documentation/type/_float.html.erb
 - app/views/explicit/documentation/type/_hash.html.erb
 - app/views/explicit/documentation/type/_integer.html.erb
 - app/views/explicit/documentation/type/_one_of.html.erb
@@ -104,6 +105,7 @@ files:
 - lib/explicit/type/date_time_unix_epoch.rb
 - lib/explicit/type/enum.rb
 - lib/explicit/type/file.rb
+- lib/explicit/type/float.rb
 - lib/explicit/type/hash.rb
 - lib/explicit/type/integer.rb
 - lib/explicit/type/literal.rb