explicit 0.1.0 → 0.2.0

data/app/views/explicit/application/_request.html.erb

@@ -0,0 +1,37 @@
+<h1 id="<%= page.anchor %>"><%= page.title %></h1>
+
+<div class="page__container">
+  <div class="page__request">
+    <div class="page__request__description markdown">
+      <%= page.description_html %>
+    </div>
+
+    <div class="params">
+      <div class="params__header">
+        <%= t("explicit.documentation.params_header") %>
+      </div>
+
+      <% page.params_properties.each do |property| %>
+        <div class="params__param">
+          <div class="params__param__name">
+            <%= property.name %>
+          </div>
+
+          <% if (description_html = property.description_html) %>
+            <div class="params__param__description markdown">
+              <%= description_html %>
+            </div>
+          <% end %>
+        </div>
+      <% end %>
+    </div>
+  </div>
+
+  <div class="page__response">
+    <% page.request.responses.map { |k, v| k }.sort.each do |status| %>
+      <div>
+        <%= status %>
+      </div>
+    <% end %>
+  </div>
+</div>

data/config/locales/en.yml

@@ -3,6 +3,7 @@ en:
     errors:
       agreement: "must be accepted"
       array: "invalid item at index(%{index}): %{error}"
+      bigdecimal: "must be a string-encoded decimal number"
       boolean: "must be a boolean"
       date_time_iso8601: "must be a valid iso8601 date time"
       date_time_posix: "must be a valid posix timestamps"
@@ -21,3 +22,5 @@ en:
       minlength: "length must be greater than or equal to %{minlength}"
       maxlength: "length must be smaller than or equal to %{maxlength}"
       format: "must have format %{regex}"
+    documentation:
+      params_header: Request params

data/lib/explicit/configuration.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Explicit
+  extend self
+
+  class Configuration
+    def initialize
+      @rescue_from_invalid_params = true
+    end
+
+    def request_examples_file_path=(path)
+      @request_examples_file_path = path
+    end
+
+    def request_examples_file_path
+      @request_examples_file_path ||= ::Rails.root&.join("public/explicit_request_examples.json")
+    end
+
+    def request_examples_persistance_enabled?
+      ENV["EXPLICIT_PERSIST_EXAMPLES"].in? %w[true 1 on]
+    end
+
+    def rescue_from_invalid_params=(enabled)
+      @rescue_from_invalid_params = enabled
+    end
+
+    def rescue_from_invalid_params?
+      @rescue_from_invalid_params
+    end
+
+    def test_runner=(test_runner)
+      @test_runner = test_runner
+    end
+
+    def test_runner
+      @test_runner ||=
+        if defined?(::RSpec) && ::RSpec.respond_to?(:configure)
+          :rspec
+        else
+          :minitest
+        end
+    end
+  end
+
+  attr_reader :configuration
+  @configuration = Configuration.new
+
+  def configure(&block)
+    block.call(@configuration)
+  end
+end

data/lib/explicit/documentation/markdown.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Explicit::Documentation::Markdown
+  extend self
+
+  def render(markdown_text)
+    offset = 0
+    markdown_text.each_char do |ch|
+      break if ch != " "
+
+      offset += 1
+    end
+
+    markdown_text = markdown_text.each_line.map do |line|
+      line[offset..-1] || "\n"
+    end
+
+    ::Commonmarker.to_html(markdown_text.join, options: {
+      parse: { smart: true },
+      render: { hardbreaks: false }
+    }).html_safe
+  end
+end

data/lib/explicit/documentation/property.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class Explicit::Documentation::Property
+  attr_reader :name, :spec
+
+  def initialize(name:, spec:)
+    @name = name
+    @spec = spec
+  end
+
+  def description_html
+    case spec
+    in [:description, markdown_text, _subspec]
+      Explicit::Documentation::Markdown.render(markdown_text).html_safe
+    else
+      nil
+    end
+  end
+end

data/lib/explicit/documentation.rb

@@ -1,33 +1,151 @@
 # frozen_string_literal: true
 
+require "commonmarker"
+
 module Explicit::Documentation
+  Section = ::Data.define(:name, :pages)
+
+  module Page
+    class Partial
+      attr_reader :title, :partial
+
+      def initialize(title:, partial:)
+        @title = title
+        @partial = partial
+      end
+
+      def request?
+        false
+      end
+
+      def anchor
+        title.dasherize
+      end
+    end
+
+    class Request
+      attr_reader :request
+
+      def initialize(request:)
+        @request = request
+      end
+
+      def request?
+        true
+      end
+
+      def title
+        @request.get_title
+      end
+
+      def description_html
+        Explicit::Documentation::Markdown.render(@request.get_description).html_safe
+      end
+
+      def anchor
+        title.dasherize
+      end
+
+      def params_properties
+        @request.params.map do |name, spec|
+          Property.new(name:, spec:)
+        end
+      end
+
+      def headers_properties
+        @request.headers.map do |name, spec|
+          Property.new(name:, spec:)
+        end
+      end
+
+      def partial
+        "request"
+      end
+    end
+  end
+
   class Builder
+    attr_reader :sections
+
+    def initialize
+      @sections = []
+      @current_section = nil
+    end
+
     def page_title(page_title)
       @page_title = page_title
     end
 
-    def primary_color(primary_color)
-      @primary_color = primary_color
-    end
+    def section(name, &block)
+      @current_section = Section.new(name:, pages: [])
+
+      block.call
+
+      @sections << @current_section
 
-    def section(name)
+      @current_section = nil
     end
 
-    def add(**opts)
+    def add(*requests, **opts)
+      raise ArgumentError(<<-MD) if @current_section.nil?
+        You must define a section before adding a page. For example:
+
+          section "Customers" do
+            add CustomersController::CreateRequest
+          end
+      MD
+
+      if requests.one?
+        @current_section.pages << Page::Request.new(request: requests.first)
+      elsif opts[:partial]
+        @current_section.pages << Page::Partial.new(title: opts[:title], partial: opts[:partial])
+      else
+        raise ArgumentError("expected request or a partial")
+      end
     end
 
     def call(request)
-      html = Explicit::ApplicationController.render(
-        partial: "documentation",
-        locals: {
-          page_title: @page_title,
-          primary_color: @primary_color,
-          sections: @sections
-        }
-      )
+      @html ||= render_documentation_page
 
-      [200, {}, [html]]
+      [200, {}, [@html]]
     end
+
+    private
+      def render_documentation_page
+        merge_request_examples_from_file!
+
+        Explicit::ApplicationController.render(
+          partial: "documentation",
+          locals: {
+            page_title: @page_title,
+            sections: @sections
+          }
+        )
+      end
+
+      def merge_request_examples_from_file!
+        return if !Explicit.configuration.request_examples_file_path
+
+        encoded = ::File.read(Explicit.configuration.request_examples_file_path)
+        examples = ::JSON.parse(encoded)
+
+        @sections.each do |section|
+          section.pages.filter(&:request?).each do |page|
+            if examples.key?(page.request.gid)
+              examples[page.request.gid].each do |example|
+                page.request.add_example(
+                  params: example["params"].with_indifferent_access,
+                  headers: example["headers"],
+                  response: {
+                    status: example.dig("response", "status"),
+                    data: example.dig("response", "data").with_indifferent_access
+                  }
+                )
+              end
+            end
+          end
+        end
+      end
   end
 
   def self.build(&block)

data/lib/explicit/engine.rb

@@ -2,8 +2,10 @@
 
 class Explicit::Engine < ::Rails::Engine
   initializer "explicit.rescue_from_invalid_params" do
-    ActiveSupport.on_load(:action_controller_api) do
-      include Explicit::Request::InvalidParams::Handler
+    if Explicit.configuration.rescue_from_invalid_params?
+      ActiveSupport.on_load(:action_controller_api) do
+        include Explicit::Request::InvalidParamsError::Rescuer
+      end
     end
   end
 end

data/lib/explicit/request/example.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Explicit::Request
+  Example = ::Data.define(:params, :headers, :response)
+end

data/lib/explicit/request/{invalid_params.rb → invalid_params_error.rb}

@@ -1,19 +1,17 @@
 # frozen_string_literal: true
 
-module Explicit::Request::InvalidParams
-  class Error < ::RuntimeError
-    attr_reader :errors
+class Explicit::Request::InvalidParamsError < ::RuntimeError
+  attr_reader :errors
 
-    def initialize(errors)
-      @errors = errors
-    end
+  def initialize(errors)
+    @errors = errors
   end
 
-  module Handler
+  module Rescuer
     extend ::ActiveSupport::Concern
 
     included do
-      rescue_from Error do |err|
+      rescue_from Explicit::Request::InvalidParamsError do |err|
         params = Explicit::Spec::Error.translate(err.errors)
 
         render json: { error: "invalid_params", params: }, status: 422

data/lib/explicit/request/invalid_response_error.rb

@@ -2,16 +2,30 @@
 
 class Explicit::Request::InvalidResponseError < ::RuntimeError
   def initialize(response, error)
+    error => [:one_of, *errs]
+    error = errs.map { translate_response_error(response, _1) }.join("\n")
+
+
     super <<-TXT
-      Response did not match expected spec.
 
-      Got:
 
-      #{response.inspect}
+Got:
+
+HTTP #{response.status} #{JSON.pretty_generate(response.data)}
 
-      Expected:
+This response doesn't match any spec. Here are the errors:
+
+#{error.presence || " ==> no response specs found for status #{response.status}"}
 
-      #{error.inspect}
     TXT
   end
+
+  private
+    def translate_response_error(response, error)
+      error = Explicit::Spec::Error.translate(error)
+
+      <<-TXT
+HTTP #{response.status} #{JSON.pretty_generate(error)}
+      TXT
+    end
 end

data/lib/explicit/request/response.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Explicit::Request
+  Response = ::Data.define(:status, :data) do
+    def dig(...) = data.dig(...)
+  end
+end

data/lib/explicit/request/route.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Explicit::Request
+  Route = ::Data.define(:method, :path) do
+    def to_s
+      "#{method.to_s.upcase} #{path}"
+    end
+  end
+end

data/lib/explicit/request.rb

@@ -1,73 +1,124 @@
 # frozen_string_literal: true
 
 class Explicit::Request
-  Route = ::Data.define(:method, :path)
-
-  class << self
-    def get(path)     = routes << Route.new(method: :get, path:)
-    def head(path)    = routes << Route.new(method: :head, path:)
-    def post(path)    = routes << Route.new(method: :post, path:)
-    def put(path)     = routes << Route.new(method: :put, path:)
-    def delete(path)  = routes << Route.new(method: :delete, path:)
-    def options(path) = routes << Route.new(method: :options, path:)
-    def patch(path)   = routes << Route.new(method: :patch, path:)
-
-    def title(text)
-      # TODO
+  attr_reader :routes, :headers, :params, :responses, :examples
+
+  def initialize(&block)
+    @routes = []
+    @headers = {}
+    @params = {}
+    @responses = Hash.new { |hash, key| hash[key] = [] }
+    @examples = Hash.new { |hash, key| hash[key] = [] }
+
+    if Explicit.configuration.rescue_from_invalid_params?
+      @responses[422] << {
+        error: "invalid_params",
+        params: [:hash, :string, :string]
+      }
     end
 
-    def description(markdown)
-      # TODO
-    end
+    instance_eval(&block)
+  end
+
+  def new(&block)
+    subrequest = self.class.new { }
+
+    subrequest.instance_variable_set(:@base_url,  @base_url)
+    subrequest.instance_variable_set(:@base_path, @base_path)
+    subrequest.instance_variable_set(:@routes,    @routes.dup)
+    subrequest.instance_variable_set(:@headers,   @headers.dup)
+    subrequest.instance_variable_set(:@params,    @params.dup)
+    subrequest.instance_variable_set(:@responses, @responses.dup)
+    subrequest.instance_variable_set(:@examples,  @examples.dup)
+
+    subrequest.tap { _1.instance_eval(&block) }
+  end
+
+  def get(path)     = @routes << Route.new(method: :get, path:)
+  def head(path)    = @routes << Route.new(method: :head, path:)
+  def post(path)    = @routes << Route.new(method: :post, path:)
+  def put(path)     = @routes << Route.new(method: :put, path:)
+  def delete(path)  = @routes << Route.new(method: :delete, path:)
+  def options(path) = @routes << Route.new(method: :options, path:)
+  def patch(path)   = @routes << Route.new(method: :patch, path:)
+
+  def base_url(url) = (@base_url = url)
+  def get_base_url = @base_url
 
-    def header(name, format)
-      raise ArgumentError("duplicated header #{name}") if headers.key?(name)
+  def base_path(prefix) = (@base_path = prefix)
+  def get_base_path = @base_path
 
-      headers[name] = format
+  def title(text) = (@title = text)
+  def get_title = @title || @routes.first.to_s
+
+  def description(markdown) = (@description = markdown)
+  def get_description = @description
+
+  def header(name, spec)
+    raise ArgumentError("duplicated header #{name}") if @headers.key?(name)
+
+    @headers[name] = spec
+  end
+
+  def param(name, spec, **options)
+    raise ArgumentError("duplicated param #{name}") if @params.key?(name)
+
+    if options[:optional]
+      spec = [:nilable, spec]
     end
 
-    def param(name, format, **options)
-      raise ArgumentError("duplicated param #{name}") if params.key?(name)
+    if (defaultval = options[:default])
+      spec = [:default, defaultval, spec]
+    end
 
-      params[name] = format
+    if (description = options[:description])
+      spec = [:description, description, spec]
     end
 
-    def response(status, format)
-      responses << { status: [:literal, status], data: format }
+    @params[name] = spec
+  end
+
+  def response(status, spec)
+    @responses[status] << spec
+  end
+
+  def add_example(params:, response:, headers: {})
+    raise ArgumentError.new("missing :status in response") if !response.key?(:status)
+    raise ArgumentError.new("missing :data in response")   if !response.key?(:data)
+
+    status, data = response.values_at(:status, :data)
+
+    response = Response.new(status:, data:)
+
+    case responses_validator(status:).call(data)
+    in [:ok, _] then nil
+    in [:error, err] then raise InvalidResponseError.new(response, err)
     end
 
-    def validate!(values)
-      params_validator = Explicit::Spec.build(params)
+    @examples[response.status] << Example.new(params:, headers:, response:)
+  end
 
-      case params_validator.call(values)
-      in [:ok, validated_data] then validated_data
-      in [:error, err] then raise InvalidParams::Error.new(err)
-      end
+  def validate!(values)
+    case params_validator.call(values)
+    in [:ok, validated_data] then validated_data
+    in [:error, err] then raise InvalidParamsError.new(err)
     end
+  end
 
-    private
-      def routes
-        @routes ||= []
-      end
-
-      def headers
-        @headers ||= {}
-      end
-
-      def params
-        @params ||= {}
-      end
-
-      INVALID_PARAMS_SPEC = {
-        status: [:literal, 422],
-        data: {
-          error: "invalid_params",
-          params: [:hash, :string, :string]
-        }
-      }.freeze
-
-      def responses
-        @responses ||= [INVALID_PARAMS_SPEC]
-      end
+  def gid
+    routes.first.to_s
   end
+
+  private
+    def params_validator
+      @params_validator ||= Explicit::Spec.build(@params)
+    end
+
+    def headers_validator
+      @headers_validator ||= Explicit::Spec.build(@headers)
+    end
+
+    def responses_validator(status:)
+      Explicit::Spec.build([:one_of, *@responses[status]])
+    end
 end

data/lib/explicit/spec/agreement.rb

@@ -3,26 +3,15 @@
 module Explicit::Spec::Agreement
   extend self
 
-  VALUES = {
-    "true" => true,
-    "on" => true,
-    "1" => true
-  }.freeze
+  VALUES = [true, "true", "on", "1", 1].freeze
+  ERROR = [:error, :agreement].freeze
+  OK = [:ok, true].freeze
 
   def build(options)
     lambda do |value|
-      value =
-        if value.is_a?(TrueClass)
-          value
-        elsif value.is_a?(::String) && options[:parse]
-          VALUES[value]
-        else
-          nil
-        end
+      return ERROR if !VALUES.include?(value)
 
-      return [:error, :agreement] if value.nil?
-
-      [:ok, value]
+      OK
     end
   end
 end

data/lib/explicit/spec/bigdecimal.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Bigdecimal
+  extend self
+
+  ERROR = [:error, :bigdecimal].freeze
+
+  def build(options)
+    lambda do |value|
+      return ERROR unless value.is_a?(::String) || value.is_a?(::Integer)
+
+      decimalvalue = BigDecimal(value)
+
+      if (min = options[:min]) && decimalvalue < min
+        return [:error, [:min, min]]
+      end
+
+      if (max = options[:max]) && decimalvalue > max
+        return [:error, [:max, max]]
+      end
+
+      [:ok, decimalvalue]
+    rescue ArgumentError
+      ERROR
+    end
+  end
+end

data/lib/explicit/spec/boolean.rb

@@ -4,26 +4,25 @@ module Explicit::Spec::Boolean
   extend self
 
   VALUES = {
+    true => true,
     "true" => true,
     "on" => true,
     "1" => true,
+    1 => true,
+    false => false,
     "false" => false,
     "off" => false,
-    "0" => false
+    "0" => false,
+    0 => false
   }.freeze
 
+  ERROR = [:error, :boolean].freeze
+
   def build(options)
     lambda do |value|
-      value =
-        if value.is_a?(TrueClass) || value.is_a?(FalseClass)
-          value
-        elsif value.is_a?(::String)
-          VALUES[value]
-        else
-          nil
-        end
+      value = VALUES[value]
 
-      return [:error, :boolean] if value.nil?
+      return ERROR if value.nil?
 
       [:ok, value]
     end