RubyGems - explicit - Versions diffs - 0.2.7 → 0.2.9 - Mend

explicit 0.2.7 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

checksums.yaml +4 -4
data/README.md +17 -1
data/app/views/explicit/documentation/_page.html.erb +2 -1
data/app/views/explicit/documentation/type/_float.html.erb +25 -0
data/config/locales/en.yml +7 -4
data/lib/explicit/documentation/output/swagger.rb +40 -11
data/lib/explicit/request.rb +33 -6
data/lib/explicit/type/date.rb +4 -4
data/lib/explicit/type/float.rb +87 -0
data/lib/explicit/type/integer.rb +13 -5
data/lib/explicit/type/one_of.rb +14 -7
data/lib/explicit/type.rb +19 -3
data/lib/explicit/version.rb +1 -1
data/lib/explicit.rb +1 -0
metadata +4 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b817ec6fe610ab86d5938a0b7958633f4f34e68a4d02b9bd8c8a50bf831622bc
-  data.tar.gz: 8cb2aae4e5a1d582734b6e1f4a917f0b07b4cf4839932dd1e2a5754f3320663b
+  metadata.gz: dd88a349ccfac424582d31d9d4f325f5ff03ede07eee06204938643b836310a5
+  data.tar.gz: 31c41a8b16b54c1d3e337cc7fb1458af43d24a97123e5f9d68470daf7b90c6dd
 SHA512:
-  metadata.gz: 1e385f89b47ec351fb000f5b9097d5ccf6233ac01dd57b9e07e87ac9488718528655ef7033686dc482dd9fc9812063f64c1f79313492157dd3ecad63055ff01b
-  data.tar.gz: 5fefc99c8c881d334364102f17e9cab4247bf0486dd5744e041654e83354e2b0265dbfaf2f41f185b354370356c33823c036b13fc2010db459e998ae0ba436ef
+  metadata.gz: c58b39e3709dbc6edba831aa1c746eb919c0c059ca2c386ac9840ff7ed101b9b0b7342e1e6885b368c3456e23b17e31fc54c8608b2d33efeacdfc3d41895ef55
+  data.tar.gz: 8e6b2055a6c55db8192a9ff5fd60773bfad06d1acc136b5056eb037ae3b76593f1d6b594c44c3c7ac63c13bb7f1a2d38a37c09cd670b40c0dd50c775595e0015

data/README.md CHANGED Viewed

@@ -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" }
@@ -550,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
@@ -561,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/_page.html.erb CHANGED Viewed

@@ -2,6 +2,7 @@
 <html>
 <head>
   <title><%= page_title || "API Documentation" %></title>
+  <meta charset="UTF-8">
   <% if favicon_url %>
     <link rel="icon" href="<%= favicon_url %>" />
@@ -50,7 +51,7 @@
           Version <%= version %>
         </div>
         <div class="p-1 w-1/2">
-          <%= link_to url_helpers.explicit_documentation_swagger_path, target: "_blank", class: "flex items-center justify-center gap-1 text-neutral-900" do %>
+          <%= link_to "https://petstore.swagger.io/?url=#{url_helpers.explicit_documentation_swagger_url(host: request.host)}", target: "_blank", class: "flex items-center justify-center gap-1 text-neutral-900" do %>
             <span>Swagger</span>
             <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" class="size-4">

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

@@ -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 CHANGED Viewed

@@ -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/output/swagger.rb CHANGED Viewed

@@ -12,6 +12,20 @@ module Explicit::Documentation::Output
     end
     def swagger_document
+      paths = build_paths_from_requests
+      securitySchemes = {}.tap do |hash|
+        requests = paths.flat_map { |path, methods| methods.values }
+        if requests.filter { _1.dig(:security, 0, :basicAuth) }.any?
+          hash[:basicAuth] = { type: "http", scheme: "basic" }
+        end
+        if requests.filter { _1.dig(:security, 0, :bearerAuth) }.any?
+          hash[:bearerAuth] = { type: "http", scheme: "bearer" }
+        end
+      end
       {
         openapi: "3.0.1",
         info: {
@@ -24,14 +38,15 @@ module Explicit::Documentation::Output
           }
         ],
         tags: build_tags_from_sections,
-        paths: build_paths_from_requests
+        paths: build_paths_from_requests,
+        components: { securitySchemes: }
       }
     end
     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 +58,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 +71,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 +84,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
@@ -86,13 +101,23 @@ module Explicit::Documentation::Output
             request = page.request
             route = request.routes.first
+            security =
+              if request.requires_basic_authorization?
+                [ { basicAuth: [] } ]
+              elsif request.requires_bearer_authorization?
+                [ { bearerAuth: [] } ]
+              else
+                nil
+              end
             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),
               requestBody: build_request_body(request),
-              responses: build_responses(request)
+              responses: build_responses(request),
+              security:
             }.compact_blank
           end
         end
@@ -102,7 +127,11 @@ module Explicit::Documentation::Output
       def build_parameters(request)
         headers =
-          request.headers_type.attributes.map do |name, type|
+          request.headers_type.attributes.filter_map do |name, type|
+            # NOTE: skip Authorization header because swagger prefers the `security` directive for basic and bearer
+            # authorization schemas. If not basic or bearer, then we add the Authorization header.
+            next if name == "Authorization" && !request.custom_authorization_format?
             {
               name: name.to_s,
               in: "header",
@@ -132,7 +161,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 +170,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 +189,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/request.rb CHANGED Viewed

@@ -12,13 +12,15 @@ class Explicit::Request
     instance_eval(&block)
+    define_missing_path_params!
     if Explicit.configuration.rescue_from_invalid_params? && @params.any?
       @responses[422] << {
         error: "invalid_params",
         params: [
           :description,
           "An object containing error messages for all invalid params",
-          [:hash, :string, :string]
+          [ :hash, :string, :string ]
         ]
       }
     end
@@ -76,19 +78,19 @@ class Explicit::Request
     raise ArgumentError("duplicated param #{name}") if @params.key?(name)
     if options[:optional]
-      type = [:nilable, type]
+      type = [ :nilable, type ]
     end
     if (defaultval = options[:default])
-      type = [:default, defaultval, type]
+      type = [ :default, defaultval, type ]
     end
     if (description = options[:description])
-      type = [:description, description, type]
+      type = [ :description, description, type ]
     end
     if @routes.first&.params&.include?(name)
-      type = [:_param_location, :path, type]
+      type = [ :_param_location, :path, type ]
     end
     @params[name] = type
@@ -140,6 +142,31 @@ class Explicit::Request
   end
   def responses_type(status:)
-    Explicit::Type.build([:one_of, *@responses[status]])
+    Explicit::Type.build([ :one_of, *@responses[status] ])
+  end
+  def custom_authorization_format?
+    @headers.key?("Authorization") && !requires_basic_authorization? && !requires_bearer_authorization?
+  end
+  def requires_basic_authorization?
+    authorization = headers_type.attributes["Authorization"]
+    authorization&.format&.to_s&.include?("Basic")
   end
+  def requires_bearer_authorization?
+    authorization = headers_type.attributes["Authorization"]
+    authorization&.format&.to_s&.include?("Bearer")
+  end
+  private
+    def define_missing_path_params!
+      @routes.first&.params&.each do |path_param_name|
+        if @params[path_param_name.to_sym].blank?
+          param(path_param_name.to_sym, :string)
+        end
+      end
+    end
 end

data/lib/explicit/type/date.rb CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

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

data/lib/explicit.rb CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: explicit
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.9
 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