explicit 0.2.0 → 0.2.2

data/lib/explicit/documentation/page/request.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Explicit::Documentation::Page
+  class Request
+    attr_reader :request
+
+    def initialize(request:)
+      @request = request
+    end
+
+    def request?
+      true
+    end
+
+    def title
+      @request.get_title
+    end
+
+    def anchor
+      title.gsub(" ", "-").downcase
+    end
+
+    def partial
+      "explicit/documentation/request"
+    end
+  end
+end

data/lib/explicit/documentation/section.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Explicit::Documentation
+  Section = ::Data.define(:name, :pages) do
+    def contains_request?
+      pages.any?(&:request?)
+    end
+  end
+end

data/lib/explicit/documentation.rb

@@ -3,156 +3,23 @@
 require "commonmarker"
 
 module Explicit::Documentation
-  Section = ::Data.define(:name, :pages)
+  extend self
 
-  module Page
-    class Partial
-      attr_reader :title, :partial
+  def new(&block)
+    engine = ::Class.new(::Rails::Engine)
 
-      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
+    builder = Builder.new(engine).tap do |builder|
+      builder.instance_eval &block
+      builder.merge_request_examples_from_file!
     end
 
-    def section(name, &block)
-      @current_section = Section.new(name:, pages: [])
-
-      block.call
-
-      @sections << @current_section
-
-      @current_section = nil
-    end
-
-    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 ||= render_documentation_page
-
-      [200, {}, [@html]]
+    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
     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)
-    builder = Builder.new.tap { _1.instance_eval &block }
-
-    ::Class.new(::Rails::Engine).tap do |engine|
-      engine.routes.draw { root to: builder }
-    end
+    engine
   end
 end

data/lib/explicit/request/example.rb

@@ -1,5 +1,54 @@
 # frozen_string_literal: true
 
 class Explicit::Request
-  Example = ::Data.define(:params, :headers, :response)
+  Example = ::Data.define(:request, :params, :headers, :response) do
+    def to_curl_lines
+      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.except(*route.params)
+
+      curl_headers =
+        if body_params.empty?
+          []
+        elsif request.accepts_file_upload?
+          ['-H "Content-Type: multipart/form-data"']
+        else
+          ['-H "Content-Type: application/json"']
+        end
+
+      headers.each do |key, value|
+        curl_headers << "-H \"#{key}: #{value}\""
+      end
+
+      curl_body =
+        if body_params.empty?
+          []
+        elsif request.accepts_file_upload?
+          file_params = request.params_type.attributes.filter do |name, type|
+            type.is_a?(Explicit::Type::File)
+          end.to_h
+
+          non_file_params = body_params.except(*file_params.keys)
+
+          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
+
+          curl_non_file_params.concat(curl_file_params)
+        else
+          # https://stackoverflow.com/questions/34847981/curl-with-multiline-of-json
+          ["-d @- << EOF\n#{JSON.pretty_generate(body_params)}\nEOF"]
+        end
+
+      [curl_request].concat(curl_headers).concat(curl_body)
+    end
+  end
 end

data/lib/explicit/request/invalid_params_error.rb

@@ -12,9 +12,7 @@ class Explicit::Request::InvalidParamsError < ::RuntimeError
 
     included do
       rescue_from Explicit::Request::InvalidParamsError do |err|
-        params = Explicit::Spec::Error.translate(err.errors)
-
-        render json: { error: "invalid_params", params: }, status: 422
+        render json: { error: "invalid_params", params: err.errors }, status: 422
       end
     end
   end

data/lib/explicit/request/invalid_response_error.rb

@@ -2,10 +2,6 @@
 
 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
 
 
@@ -13,19 +9,10 @@ Got:
 
 HTTP #{response.status} #{JSON.pretty_generate(response.data)}
 
-This response doesn't match any spec. Here are the errors:
+This response doesn't match any type. Here are the errors:
 
-#{error.presence || " ==> no response specs found for status #{response.status}"}
+#{error.presence || " ==> no response types found for status #{response.status}"}
 
     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/route.rb

@@ -5,5 +5,23 @@ class Explicit::Request
     def to_s
       "#{method.to_s.upcase} #{path}"
     end
+
+    def params
+      path.split("/").filter_map do |part|
+        part[1..-1].to_sym if part.start_with?(":")
+      end
+    end
+
+    def replace_path_params(values)
+      values.reduce(path) do |acc_path, (key, value)|
+        acc_path.gsub(":#{key}", value.to_s)
+      end
+    end
+
+    def path_with_curly_syntax
+      params.reduce(path) do |acc_path, param|
+        acc_path.gsub(":#{param}", "{#{param}}")
+      end
+    end
   end
 end

data/lib/explicit/request.rb

@@ -13,7 +13,11 @@ class Explicit::Request
     if Explicit.configuration.rescue_from_invalid_params?
       @responses[422] << {
         error: "invalid_params",
-        params: [:hash, :string, :string]
+        params: [
+          :description,
+          "An object containing error messages for all invalid params",
+          [:hash, :string, :string]
+        ]
       }
     end
 
@@ -28,8 +32,14 @@ class Explicit::Request
     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)
+
+    @responses.each do |status, types|
+      subrequest.responses[status] = types.dup
+    end
+
+    @examples.each do |status, examples|
+      subrequest.examples[status] = examples.dup
+    end
 
     subrequest.tap { _1.instance_eval(&block) }
   end
@@ -54,32 +64,36 @@ class Explicit::Request
   def description(markdown) = (@description = markdown)
   def get_description = @description
 
-  def header(name, spec)
+  def header(name, type)
     raise ArgumentError("duplicated header #{name}") if @headers.key?(name)
 
-    @headers[name] = spec
+    @headers[name] = type
   end
 
-  def param(name, spec, **options)
+  def param(name, type, **options)
     raise ArgumentError("duplicated param #{name}") if @params.key?(name)
 
     if options[:optional]
-      spec = [:nilable, spec]
+      type = [:nilable, type]
     end
 
     if (defaultval = options[:default])
-      spec = [:default, defaultval, spec]
+      type = [:default, defaultval, type]
     end
 
     if (description = options[:description])
-      spec = [:description, description, spec]
+      type = [:description, description, type]
     end
 
-    @params[name] = spec
+    if @routes.first&.params&.include?(name)
+      type = [:_param_location, :path, type]
+    end
+
+    @params[name] = type
   end
 
-  def response(status, spec)
-    @responses[status] << spec
+  def response(status, typespec)
+    @responses[status] << typespec
   end
 
   def add_example(params:, response:, headers: {})
@@ -90,16 +104,16 @@ class Explicit::Request
 
     response = Response.new(status:, data:)
 
-    case responses_validator(status:).call(data)
+    case responses_type(status:).validate(data)
     in [:ok, _] then nil
     in [:error, err] then raise InvalidResponseError.new(response, err)
     end
 
-    @examples[response.status] << Example.new(params:, headers:, response:)
+    @examples[response.status] << Example.new(request: self, params:, headers:, response:)
   end
 
   def validate!(values)
-    case params_validator.call(values)
+    case params_type.validate(values)
     in [:ok, validated_data] then validated_data
     in [:error, err] then raise InvalidParamsError.new(err)
     end
@@ -109,16 +123,21 @@ class Explicit::Request
     routes.first.to_s
   end
 
-  private
-    def params_validator
-      @params_validator ||= Explicit::Spec.build(@params)
+  def accepts_file_upload?
+    params_type.attributes.any? do |name, type|
+      type.is_a?(Explicit::Type::File)
     end
+  end
 
-    def headers_validator
-      @headers_validator ||= Explicit::Spec.build(@headers)
-    end
+  def headers_type
+    @headers_type ||= Explicit::Type.build(@headers)
+  end
 
-    def responses_validator(status:)
-      Explicit::Spec.build([:one_of, *@responses[status]])
-    end
+  def params_type
+    @params_type ||= Explicit::Type.build(@params)
+  end
+
+  def responses_type(status:)
+    Explicit::Type.build([:one_of, *@responses[status]])
+  end
 end

data/lib/explicit/test_helper/example_recorder.rb

@@ -25,6 +25,7 @@ class Explicit::TestHelper::ExampleRecorder
 
   def add(request_gid:, params:, headers:, response:)
     @examples[request_gid] << Explicit::Request::Example.new(
+      request: nil,
       params:,
       headers:,
       response:
@@ -32,7 +33,11 @@ class Explicit::TestHelper::ExampleRecorder
   end
 
   def save!
-    total_examples_count = @examples.sum { |_, examples| examples.size }
+    examples_hash = @examples.keys.map do |key|
+      [key, @examples[key]]
+    end.to_h
+
+    total_examples_count = examples_hash.sum { _2.size }
     file_path = Explicit.configuration.request_examples_file_path
 
     puts "" if Explicit.configuration.test_runner == :rspec
@@ -43,6 +48,6 @@ class Explicit::TestHelper::ExampleRecorder
     puts "  [Explicit] ========="
     puts "" if Explicit.configuration.test_runner == :minitest
 
-    ::File.write(file_path, @examples.to_json, mode: "w")
+    ::File.write(file_path, examples_hash.to_json, mode: "w")
   end
 end

data/lib/explicit/test_helper.rb

@@ -19,8 +19,9 @@ module Explicit::TestHelper
 
   included do
     if Explicit.configuration.test_runner == :minitest
-      # TODO: improve this logic
-      running_in_parallel = Minitest.parallel_executor.is_a?(ActiveSupport::Testing::ParallelizeExecutor)
+      running_in_parallel = Minitest.parallel_executor.is_a?(
+        ActiveSupport::Testing::ParallelizeExecutor
+      )
 
       if running_in_parallel
         uri = Explicit::TestHelper::ExampleRecorder.start_service
@@ -48,16 +49,21 @@ module Explicit::TestHelper
       DESC
     end
 
-    process(route.method, route.path, params:, headers:)
+    method = route.method
+    path = (request.get_base_path || "") + route.path
+
+    process(method, path, params:, headers:)
 
     response = Explicit::Request::Response.new(
       status: @response.status,
       data: @response.parsed_body.deep_symbolize_keys
     )
 
-    ensure_response_matches_spec!(request, response)
+    ensure_response_matches_documented_type!(request, response)
 
     if opts[:save_as_example]
+      params = replace_uploaded_files_with_filenames(params)
+
       ExampleRecorder.instance.add(
         request_gid: request.gid,
         params:,
@@ -69,12 +75,24 @@ module Explicit::TestHelper
     response
   end
 
-  def ensure_response_matches_spec!(request, response)
-    validator = request.send(:responses_validator, status: response.status)
+  def ensure_response_matches_documented_type!(request, response)
+    responses_type = request.responses_type(status: response.status)
 
-    case validator.call(response.data.with_indifferent_access)
+    case responses_type.validate(response.data.with_indifferent_access)
     in [:ok, _] then :all_good
     in [:error, err] then raise Explicit::Request::InvalidResponseError.new(response, err)
     end
   end
+
+  def replace_uploaded_files_with_filenames(hash)
+    hash.to_h do |key, value|
+      if Explicit::Type::File::FILE_CLASSES.any? { value.is_a?(_1) }
+        [key, "@#{value.original_filename}"]
+      elsif value.is_a?(::Hash)
+        [key, replace_uploaded_files_with_filenames(value)]
+      else
+        [key, value]
+      end
+    end
+  end
 end

data/lib/explicit/type/agreement.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class Explicit::Type::Agreement < Explicit::Type
+  VALUES = [true, "true", "on", "1", 1].freeze
+  OK = [:ok, true].freeze
+
+  def validate(value)
+    if VALUES.include?(value)
+      OK
+    else
+      [:error, error_i18n("agreement")]
+    end
+  end
+
+  concerning :Webpage do
+    def summary
+      "boolean"
+    end
+
+    def partial
+      "explicit/documentation/type/agreement"
+    end
+
+    def has_details?
+      true
+    end
+  end
+
+  concerning :Swagger do
+    def swagger_schema
+      {
+        type: "boolean",
+        description: swagger_description([
+          swagger_i18n("agreement")
+        ])
+      }
+    end
+  end
+end

data/lib/explicit/type/array.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+class Explicit::Type::Array < Explicit::Type
+  attr_reader :itemtype, :empty
+
+  def initialize(itemtype:, empty: true)
+    @itemtype = Explicit::Type.build(itemtype)
+    @empty = empty
+  end
+
+  def validate(values)
+    return [:error, :array] if !values.is_a?(::Array)
+
+    if values.empty? && !empty
+      return [:error, :empty]
+    end
+
+    validated = []
+
+    values.each.with_index do |value, index|
+      case itemtype.validate(value)
+      in [:ok, value]
+        validated << value
+      in [:error, error]
+        return [:error, error_i18n("array", index:, error:)]
+      end
+    end
+
+    [:ok, validated]
+  end
+
+  concerning :Webpage do
+    def summary
+      "array of #{itemtype.summary}"
+    end
+
+    def partial
+      "explicit/documentation/type/array"
+    end
+
+    def has_details?
+      true
+    end
+  end
+
+  concerning :Swagger do
+    def swagger_schema
+      {
+        type: "array",
+        items: itemtype.swagger_schema,
+        minItems: empty ? 0 : 1,
+        description: swagger_description([])
+      }.compact_blank
+    end
+  end
+end