explicit 0.2.12 → 0.2.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 954701c8ac0b7cd387f9dd6129739a59c624390c56c73baa507340aca73093de
-  data.tar.gz: 5372f09b33652971b8df685721d7c8a93782054ac8bc0a91a67b1c3cbf1bbf47
+  metadata.gz: d263cb4a6086cfbfce9e14e8b982891f58a2037457ee07138d7cdd4d7d811e87
+  data.tar.gz: 31302fbc977b6f96d586e453d5d7dfa9708e9ae02423c69a2c2052f23f85cc09
 SHA512:
-  metadata.gz: 47e20235b39777a2c42a192ca6e1a060d336b94808afdb825204e947bc511bda25cc2c8e58a3c830f768c245d8b760d159829f525adaff01e22e6c758db57e42
-  data.tar.gz: 0d65d5a475676aa645bd757fbc38f05ea97ab64476cf113f31e28a375f2494f45dd4ddf1391cd84f3d4cffbb96e054f3e620bc6a7569558ff2fa1ac92364dc27
+  metadata.gz: 7683a050bc830faa883055fec094ffa5304fb2938071c8cc6cb5a4b289a98cb87ba6e965b299bef09895a2687fd3389672351b26975fa59616f2b8d136a003cb
+  data.tar.gz: 71a80ef0f2e7259af2d217e6ef6e8f6995ee84d30fd65dbec521eeb7afd4d901374b5a5ec09d3e5a57238990bac629dd34f9311e5af5105c98438d3e6f0098e5

data/README.md

@@ -41,6 +41,7 @@ documented types at runtime.
    - [Changing examples file path](#changing-examples-file-path)
    - [Customizing error messages](#customizing-error-messages)
    - [Customizing error serialization](#customizing-error-serialization)
+   - [Raise on invalid example](#raise-on-invalid-example)
 
 # Installation
 
@@ -62,10 +63,13 @@ available:
 - `title(text)` - Adds a title to the request. Displayed in documentation.
 - `description(text)` - Adds a description to the endpoint. Displayed in
   documentation. Markdown supported.
-- `header(name, type)` - Adds a type to the request header.
+- `header(name, type, options = {})` - Adds a type to the request header.
+  - The following options are available:
+    - `auth: :bearer` - Sets the authentication to [bearer](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/).
+    - `auth: :basic` - Sets the authentication to [basic](https://swagger.io/docs/specification/v3_0/authentication/basic-authentication/).
 - `param(name, type, options = {})` - Adds a type to the request param.
   It works for params in the request body, query string and path params.
-  - The following conveniences are available via options:
+  - The following options are available:
     - `optional: true` - Makes the param nilable.
     - `default: value` - Sets a default value to the param, which makes it optional.
     - `description: "text"` - Adds a documentation to the param. Markdown supported.
@@ -146,7 +150,7 @@ 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}/]
+  header "Authorization", [:string, format: /Bearer [a-zA-Z0-9]{20}/], auth: :bearer
 
   response 403, { error: "unauthorized" }
 end
@@ -699,3 +703,10 @@ class ApplicationController < ActionController::API
   end
 end
 ```
+
+### Raise on invalid example
+
+```ruby
+config.raise_on_invalid_example = true # default is false
+config.raise_on_invalid_example = ::Rails.env.development? # recommended
+```

data/lib/explicit/configuration.rb

@@ -28,6 +28,14 @@ module Explicit
       @rescue_from_invalid_params
     end
 
+    def raise_on_invalid_example=(enabled)
+      @raise_on_invalid_example = enabled
+    end
+
+    def raise_on_invalid_example?
+      @raise_on_invalid_example
+    end
+
     def test_runner=(test_runner)
       @test_runner = test_runner
     end
@@ -48,4 +56,4 @@ module Explicit
   def configure(&block)
     block.call(@configuration)
   end
-end
+end

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

@@ -152,7 +152,18 @@ module Explicit::Documentation::Output
             }
           end
 
-        headers + path_params
+        query_params =
+          request.params_type.query_params_type.attributes.map do |name, type|
+            {
+              name: name.to_s,
+              in: "query",
+              required: type.required?,
+              schema: type.swagger_schema,
+              style: "simple"
+            }
+          end
+
+        headers + path_params + query_params
       end
 
       def build_request_body(request)

data/lib/explicit/documentation.rb

@@ -14,7 +14,7 @@ module Explicit::Documentation
     end
 
     engine.define_singleton_method(:documentation_builder) { builder }
-    
+
     engine.routes.draw do
       get "/", to: builder.webpage, as: :explicit_documentation_webpage
       get "/swagger", to: builder.swagger, as: :explicit_documentation_swagger

data/lib/explicit/request/example.rb

@@ -6,10 +6,11 @@ class Explicit::Request
       route = request.routes.first
       method = route.method.to_s.upcase
       path = route.replace_path_params(params)
-      url = "#{request.get_base_url}#{request.get_base_path}#{path}"
-      curl_request = "curl -X#{method} \"#{url}\""
+      body_params = params.slice(*request.params_type.body_params_type.attributes.keys)
+      query_params = params.slice(*request.params_type.query_params_type.attributes.keys)
 
-      body_params = params.except(*route.params)
+      url = "#{request.get_base_url}#{request.get_base_path}#{path}#{query_params.present? ? "?#{query_params.to_query}" : ""}"
+      curl_request = "curl -X#{method} \"#{url}\""
 
       curl_headers =
         if body_params.empty?
@@ -37,7 +38,7 @@ class Explicit::Request
           curl_non_file_params = non_file_params.to_query.split("&").map do |key_value|
             "-F \"#{CGI.unescape(key_value).gsub('"', '\"')}\""
           end
-          
+
           curl_file_params = file_params.map do |name, _|
             "-F #{name}=\"#{body_params[name]}\""
           end

data/lib/explicit/request/route.rb

@@ -12,6 +12,10 @@ class Explicit::Request
       end
     end
 
+    def accepts_request_body?
+      method == :post || method == :put || method == :patch
+    end
+
     def replace_path_params(values)
       values.reduce(path) do |acc_path, (key, value)|
         acc_path.gsub(":#{key}", value.to_s)
@@ -24,4 +28,4 @@ class Explicit::Request
       end
     end
   end
-end
+end

data/lib/explicit/request.rb

@@ -68,9 +68,13 @@ class Explicit::Request
   def description(markdown) = (@description = markdown)
   def get_description = @description
 
-  def header(name, type)
+  def header(name, type,  **options)
     raise ArgumentError("duplicated header #{name}") if @headers.key?(name)
 
+    if (auth_type = options[:auth])
+      type = [ :_auth_type, auth_type, type ]
+    end
+
     @headers[name] = type
   end
 
@@ -91,6 +95,10 @@ class Explicit::Request
 
     if @routes.first&.params&.include?(name)
       type = [ :_param_location, :path, type ]
+    elsif @routes.first&.accepts_request_body?
+      type = [ :_param_location, :body, type ]
+    else
+      type = [ :_param_location, :query, type ]
     end
 
     @params[name] = type
@@ -109,8 +117,15 @@ class Explicit::Request
     response = Response.new(status:, data:)
 
     case responses_type(status:).validate(data)
-    in [:ok, _] then nil
-    in [:error, err] then raise InvalidResponseError.new(response, err)
+    in [:ok, _]
+      nil
+
+    in [:error, err]
+      if ::Explicit.configuration.raise_on_invalid_example?
+        raise InvalidResponseError.new(response, err)
+      else
+        ::Rails.logger.error("[Explicit] Invalid response for #{gid} with status #{status}: #{err}")
+      end
     end
 
     @examples[response.status] << Example.new(request: self, params:, headers:, response:)
@@ -152,13 +167,13 @@ class Explicit::Request
   def requires_basic_authorization?
     authorization = headers_type.attributes["Authorization"]
 
-    authorization&.format&.to_s&.include?("Basic")
+    authorization&.auth_basic? || authorization&.format&.to_s&.include?("Basic")
   end
 
   def requires_bearer_authorization?
     authorization = headers_type.attributes["Authorization"]
 
-    authorization&.format&.to_s&.include?("Bearer")
+    authorization&.auth_bearer? || authorization&.format&.to_s&.include?("Bearer")
   end
 
   private

data/lib/explicit/test_helper.rb

@@ -69,7 +69,7 @@ module Explicit::TestHelper
       raise <<~TXT
         Unexpected HTML response:
 
-        #{html.text}
+        #{html.text.gsub(/^\s+$\n/, '')}
       TXT
     end
 

data/lib/explicit/type/modifiers/auth_type.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Explicit::Type::Modifiers::AuthType
+  extend self
+
+  def apply(auth_type, type)
+    Explicit::Type.build(type).tap do |type|
+      type.auth_type = auth_type
+    end
+  end
+end

data/lib/explicit/type/record.rb

@@ -41,9 +41,17 @@ class Explicit::Type::Record < Explicit::Type
     self.class.new(attributes: path_params)
   end
 
+  def query_params_type
+    query_params = @attributes.filter do |name, type|
+      type.param_location_query?
+    end
+
+    self.class.new(attributes: query_params)
+  end
+
   def body_params_type
     body_params = @attributes.filter do |name, type|
-      !type.param_location_path?
+      type.param_location_body?
     end
 
     self.class.new(attributes: body_params)

data/lib/explicit/type.rb

@@ -99,17 +99,36 @@ class Explicit::Type
     in [:nilable, type]
       Explicit::Type::Modifiers::Nilable.apply(type)
 
+    in [:_auth_type, auth_type, type]
+      Explicit::Type::Modifiers::AuthType.apply(auth_type, type)
+
     in [:_param_location, param_location, type]
       Explicit::Type::Modifiers::ParamLocation.apply(param_location, type)
     end
   end
 
-  attr_accessor :description, :default, :nilable, :param_location
+  attr_accessor :description, :default, :nilable, :param_location, :auth_type
 
   def param_location_path?
     param_location == :path
   end
 
+  def param_location_query?
+    param_location == :query
+  end
+
+  def param_location_body?
+    param_location == :body
+  end
+
+  def auth_basic?
+    auth_type == :basic
+  end
+
+  def auth_bearer?
+    auth_type == :bearer
+  end
+
   def required?
     !nilable
   end

data/lib/explicit/version.rb

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

data/lib/explicit.rb

@@ -44,6 +44,7 @@ require "explicit/type/one_of"
 require "explicit/type/record"
 require "explicit/type/string"
 
+require "explicit/type/modifiers/auth_type"
 require "explicit/type/modifiers/default"
 require "explicit/type/modifiers/description"
 require "explicit/type/modifiers/nilable"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: explicit
 version: !ruby/object:Gem::Version
-  version: 0.2.12
+  version: 0.2.13
 platform: ruby
 authors:
 - Luiz Vasconcellos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-03-30 00:00:00.000000000 Z
+date: 2025-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -111,6 +111,7 @@ files:
 - lib/explicit/type/hash.rb
 - lib/explicit/type/integer.rb
 - lib/explicit/type/literal.rb
+- lib/explicit/type/modifiers/auth_type.rb
 - lib/explicit/type/modifiers/default.rb
 - lib/explicit/type/modifiers/description.rb
 - lib/explicit/type/modifiers/nilable.rb