explicit 0.2.0 → 0.2.2

data/lib/explicit/type/string.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+class Explicit::Type::String < Explicit::Type
+  attr_reader :empty, :strip, :format, :minlength, :maxlength, :downcase
+
+  def initialize(empty: nil, strip: nil, format: nil, minlength: nil, maxlength: nil, downcase: false)
+    @empty = empty
+    @strip = strip
+    @format = format
+    @minlength = minlength
+    @maxlength = maxlength
+    @downcase = downcase
+  end
+
+  def validate(value)
+    return [:error, error_i18n("string")] if !value.is_a?(::String)
+
+    value = value.strip if strip
+    value = value.downcase if downcase
+
+    if empty == false && value.empty?
+      return [:error, error_i18n("empty")]
+    end
+
+    if minlength && value.length < minlength
+      return [:error, error_i18n("minlength", minlength:)]
+    end
+
+    if maxlength && value.length > maxlength
+      return [:error, error_i18n("maxlength", maxlength:)]
+    end
+
+    if format && !format.match?(value)
+      return [:error, error_i18n("format", regex: format.inspect)]
+    end
+
+    [:ok, value]
+  end
+
+  concerning :Webpage do
+    def summary
+      "string"
+    end
+
+    def partial
+      "explicit/documentation/type/string"
+    end
+
+    def has_details?
+      !empty.nil? || format.present? || minlength.present? || maxlength.present?
+    end
+  end
+
+  concerning :Swagger do
+    def swagger_schema
+      {
+        type: "string",
+        pattern: format&.inspect,
+        minLength: minlength || (empty == false ? 1 : nil),
+        maxLength: maxlength,
+        description: swagger_description([
+          empty == false ? swagger_i18n("string_not_empty") : nil,
+          downcase == true ? swagger_i18n("string_downcase") : nil
+        ])
+      }.compact_blank
+    end
+  end
+end

data/lib/explicit/type.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+class Explicit::Type
+  module Modifiers; end
+
+  def self.build(type)
+    case type
+    in :agreement
+      Explicit::Type::Agreement.new
+
+    in [:array, itemtype]
+      Explicit::Type::Array.new(itemtype:)
+    in [:array, itemtype, options]
+      Explicit::Type::Array.new(itemtype:, **options)
+
+    in :bigdecimal
+      Explicit::Type::BigDecimal.new
+    in [:bigdecimal, options]
+      Explicit::Type::BigDecimal.new(**options)
+
+    in :boolean
+      Explicit::Type::Boolean.new
+
+    in :date_time_iso8601
+      Explicit::Type::DateTimeISO8601.new
+    in :date_time_posix
+      Explicit::Type::DateTimePosix.new
+
+    in [:hash, keytype, valuetype]
+      Explicit::Type::Hash.new(keytype:, valuetype:)
+    in [:hash, keytype, valuetype, options]
+      Explicit::Type::Hash.new(keytype:, valuetype:, **options)
+
+    in [:enum, allowed_values]
+      Explicit::Type::Enum.new(allowed_values)
+
+    in :file
+      Explicit::Type::File.new
+    in [:file, options]
+      Explicit::Type::File.new(**options)
+
+    in :integer
+      Explicit::Type::Integer.new
+    in [:integer, options]
+      Explicit::Type::Integer.new(**options)
+
+    in [:literal, value]
+      Explicit::Type::Literal.new(value:)
+    in ::String
+      Explicit::Type::Literal.new(value: type)
+
+    in [:one_of, *subtypes]
+      Explicit::Type::OneOf.new(subtypes:)
+
+    in ::Hash
+      Explicit::Type::Record.new(attributes: type)
+
+    in :string
+      Explicit::Type::String.new
+    in [:string, options]
+      Explicit::Type::String.new(**options)
+
+    ## MODIFIERS
+
+    in [:default, default, subtype]
+      Explicit::Type::Modifiers::Default.apply(default, subtype)
+
+    in [:description, description, subtype]
+      Explicit::Type::Modifiers::Description.apply(description, subtype)
+
+    in [:nilable, type]
+      Explicit::Type::Modifiers::Nilable.apply(type)
+
+    in [:_param_location, param_location, type]
+      Explicit::Type::Modifiers::ParamLocation.apply(param_location, type)
+    end
+  end
+
+  attr_accessor :description, :default, :nilable, :param_location
+
+  def param_location_path?
+    param_location == :path
+  end
+
+  def required?
+    !nilable
+  end
+
+  def error_i18n(name, context = {})
+    key = "explicit.errors.#{name}"
+
+    ::I18n.t(key, **context)
+  end
+
+  def swagger_i18n(name, context = {})
+    key = "explicit.swagger.#{name}"
+
+    ::I18n.t(key, **context)
+  end
+
+  def swagger_description(extras)
+    extras = extras.compact_blank
+
+    if description.present? && extras.empty?
+      description
+    elsif description.present? && extras.any?
+      description + "\n\n" + extras.compact_blank.join("\n")
+    else
+      extras.compact_blank.join("\n")
+    end
+  end
+end

data/lib/explicit/version.rb

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

data/lib/explicit.rb

@@ -1,10 +1,17 @@
+require "active_support/core_ext/module/concerning"
+
 require "explicit/configuration"
 require "explicit/engine"
 require "explicit/version"
 
 require "explicit/documentation"
+require "explicit/documentation/builder"
 require "explicit/documentation/markdown"
-require "explicit/documentation/property"
+require "explicit/documentation/section"
+require "explicit/documentation/output/swagger"
+require "explicit/documentation/output/webpage"
+require "explicit/documentation/page/partial"
+require "explicit/documentation/page/request"
 
 require "explicit/test_helper"
 require "explicit/test_helper/example_recorder"
@@ -16,20 +23,23 @@ require "explicit/request/invalid_response_error"
 require "explicit/request/response"
 require "explicit/request/route"
 
-require "explicit/spec"
-require "explicit/spec/agreement"
-require "explicit/spec/array"
-require "explicit/spec/bigdecimal"
-require "explicit/spec/boolean"
-require "explicit/spec/date_time_iso8601"
-require "explicit/spec/date_time_posix"
-require "explicit/spec/default"
-require "explicit/spec/error"
-require "explicit/spec/hash"
-require "explicit/spec/inclusion"
-require "explicit/spec/integer"
-require "explicit/spec/literal"
-require "explicit/spec/nilable"
-require "explicit/spec/one_of"
-require "explicit/spec/record"
-require "explicit/spec/string"
+require "explicit/type"
+require "explicit/type/agreement"
+require "explicit/type/array"
+require "explicit/type/big_decimal"
+require "explicit/type/boolean"
+require "explicit/type/date_time_iso8601"
+require "explicit/type/date_time_posix"
+require "explicit/type/enum"
+require "explicit/type/file"
+require "explicit/type/hash"
+require "explicit/type/integer"
+require "explicit/type/literal"
+require "explicit/type/one_of"
+require "explicit/type/record"
+require "explicit/type/string"
+
+require "explicit/type/modifiers/default"
+require "explicit/type/modifiers/description"
+require "explicit/type/modifiers/nilable"
+require "explicit/type/modifiers/param_location"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: explicit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Luiz Vasconcellos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-12-29 00:00:00.000000000 Z
+date: 2025-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -38,8 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: Explicit is a validation and documentation library for JSON APIs that
-  enforces documented specs at runtime
+description: Explicit is a validation and documentation library for REST APIs that
+  enforces documented types at runtime
 email:
 - luizpvasc@gmail.com
 executables: []
@@ -51,15 +51,35 @@ files:
 - Rakefile
 - app/controllers/explicit/application_controller.rb
 - app/helpers/explicit/application_helper.rb
-- app/views/explicit/application/_documentation.html.erb
-- app/views/explicit/application/_request.html.erb
+- app/views/explicit/documentation/_attribute.html.erb
+- app/views/explicit/documentation/_page.html.erb
+- app/views/explicit/documentation/_request.html.erb
+- app/views/explicit/documentation/request/_examples.html.erb
+- app/views/explicit/documentation/type/_agreement.html.erb
+- app/views/explicit/documentation/type/_array.html.erb
+- app/views/explicit/documentation/type/_big_decimal.html.erb
+- app/views/explicit/documentation/type/_boolean.html.erb
+- app/views/explicit/documentation/type/_date_time_iso8601.html.erb
+- app/views/explicit/documentation/type/_date_time_posix.html.erb
+- app/views/explicit/documentation/type/_enum.html.erb
+- app/views/explicit/documentation/type/_file.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
+- app/views/explicit/documentation/type/_record.html.erb
+- app/views/explicit/documentation/type/_string.html.erb
 - config/locales/en.yml
 - config/routes.rb
 - lib/explicit.rb
 - lib/explicit/configuration.rb
 - lib/explicit/documentation.rb
+- lib/explicit/documentation/builder.rb
 - lib/explicit/documentation/markdown.rb
-- lib/explicit/documentation/property.rb
+- lib/explicit/documentation/output/swagger.rb
+- lib/explicit/documentation/output/webpage.rb
+- lib/explicit/documentation/page/partial.rb
+- lib/explicit/documentation/page/request.rb
+- lib/explicit/documentation/section.rb
 - lib/explicit/engine.rb
 - lib/explicit/request.rb
 - lib/explicit/request/example.rb
@@ -67,25 +87,27 @@ files:
 - lib/explicit/request/invalid_response_error.rb
 - lib/explicit/request/response.rb
 - lib/explicit/request/route.rb
-- lib/explicit/spec.rb
-- lib/explicit/spec/agreement.rb
-- lib/explicit/spec/array.rb
-- lib/explicit/spec/bigdecimal.rb
-- lib/explicit/spec/boolean.rb
-- lib/explicit/spec/date_time_iso8601.rb
-- lib/explicit/spec/date_time_posix.rb
-- lib/explicit/spec/default.rb
-- lib/explicit/spec/error.rb
-- lib/explicit/spec/hash.rb
-- lib/explicit/spec/inclusion.rb
-- lib/explicit/spec/integer.rb
-- lib/explicit/spec/literal.rb
-- lib/explicit/spec/nilable.rb
-- lib/explicit/spec/one_of.rb
-- lib/explicit/spec/record.rb
-- lib/explicit/spec/string.rb
 - lib/explicit/test_helper.rb
 - lib/explicit/test_helper/example_recorder.rb
+- lib/explicit/type.rb
+- lib/explicit/type/agreement.rb
+- lib/explicit/type/array.rb
+- lib/explicit/type/big_decimal.rb
+- lib/explicit/type/boolean.rb
+- lib/explicit/type/date_time_iso8601.rb
+- lib/explicit/type/date_time_posix.rb
+- lib/explicit/type/enum.rb
+- lib/explicit/type/file.rb
+- lib/explicit/type/hash.rb
+- lib/explicit/type/integer.rb
+- lib/explicit/type/literal.rb
+- lib/explicit/type/modifiers/default.rb
+- lib/explicit/type/modifiers/description.rb
+- lib/explicit/type/modifiers/nilable.rb
+- lib/explicit/type/modifiers/param_location.rb
+- lib/explicit/type/one_of.rb
+- lib/explicit/type/record.rb
+- lib/explicit/type/string.rb
 - lib/explicit/version.rb
 - lib/tasks/schema/api_tasks.rake
 homepage: https://github.com/luizpvas/explicit
@@ -113,5 +135,5 @@ requirements: []
 rubygems_version: 3.4.22
 signing_key: 
 specification_version: 4
-summary: Explicit is a validation and documentation library for JSON APIs
+summary: Explicit is a validation and documentation library for REST APIs
 test_files: []

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

@@ -1,136 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-  <title><%= local_assigns[:page_title] || "API Documentation" %></title>
-
-  <style>
-    html, body {
-      font-family: sans-serif;
-      font-size: 14px;
-      margin: 0;
-      padding: 0;
-
-      --color-neutral-100: #f5f5f5;
-      --color-neutral-200: #e5e5e5;
-      --color-neutral-300: #d4d4d8;
-      --color-neutral-400: #a3a3a3;
-      --color-neutral-500: #737373;
-      --color-neutral-600: #525252;
-    }
-
-    .container {
-      display: flex;
-    }
-
-    .navigation {
-      background-color: var(--color-neutral-100);
-      border-right: 1px solid var(--color-neutral-300);
-      width: 380px;
-      height: 100vh;
-    }
-    .navigation__section {
-    }
-    .navigation__section__page {
-      display: block;
-    }
-
-    .main {
-      flex-grow: 1;
-      width: 100%;
-      height: 100vh;
-      overflow: auto;
-    }
-
-    .page {
-      padding: 0 2rem;
-      margin-bottom: 100px;
-    }
-    .page:not(:first-of-type) {
-      border-top: 1px solid var(--color-neutral-200);
-    }
-    .page__container {
-      display: flex;
-      gap: 1rem;
-    }
-    .page__request {
-      width: 50%;
-    }
-    .page__request__description {
-      line-height: 1.6rem;
-    }
-    .page__response {
-      width: 50%;
-    }
-
-    .markdown code {
-      background: var(--color-neutral-100);
-      color: var(--color-neutral-900);
-    }
-    .markdown p:first-of-type {
-      margin-block-start: 0em;
-    }
-    .markdown p:last-of-type {
-      margin-block-end: 0em;
-    }
-
-    .params {
-      margin-top: 1rem;
-      border: 1px solid var(--color-neutral-200);
-      border-radius: 8px;
-    }
-    .params__header {
-      padding: 5px;
-      text-align: center;
-
-      font-size: 12px;
-      text-transform: uppercase;
-      color: var(--color-neutral-500);
-      border-bottom: 1px solid var(--color-neutral-200);
-
-      background-color: var(--color-neutral-100);
-      border-top-left-radius: 8px;
-      border-top-right-radius: 8px;
-    }
-    .params__param {
-      padding: 0.8rem;
-    }
-    .params__param:not(:last-of-type) {
-      border-bottom: 1px solid var(--color-neutral-200);
-    }
-    .params__param__name {
-      font-family: monospace;
-      font-weight: bold;
-    }
-    .params__param__description {
-      margin-top: 0.5rem;
-      color: var(--color-neutral-500);
-    }
-  </style>
-</head>
-
-<body>
-  <div class="container">
-    <section class="navigation">
-      <% sections.each do |section| %>
-        <details class="navigation__section" open>
-          <summary><%= section.name %></summary>
-
-          <% section.pages.each do |page| %>
-            <%= link_to page.title, "##{page.anchor}", class: "navigation__section__page" %>
-          <% end %>
-        </details>
-      <% end %>
-    </section>
-
-    <main class="main">
-      <% sections.each do |section| %>
-        <% section.pages.each do |page| %>
-          <div class="page">
-            <%= render partial: page.partial, locals: { page: } %>
-          </div>
-        <% end %>
-      <% end %>
-    </main>
-  </div>
-</body>
-</html>

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

@@ -1,37 +0,0 @@
-<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/lib/explicit/documentation/property.rb

@@ -1,19 +0,0 @@
-# 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/spec/agreement.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module Explicit::Spec::Agreement
-  extend self
-
-  VALUES = [true, "true", "on", "1", 1].freeze
-  ERROR = [:error, :agreement].freeze
-  OK = [:ok, true].freeze
-
-  def build(options)
-    lambda do |value|
-      return ERROR if !VALUES.include?(value)
-
-      OK
-    end
-  end
-end

data/lib/explicit/spec/array.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module Explicit::Spec::Array
-  extend self
-
-  def build(itemspec, options)
-    itemspec_validator = Explicit::Spec.build(itemspec)
-
-    lambda do |values|
-      return [:error, :array] if !values.is_a?(::Array)
-
-      if options[:empty] == false && values.empty?
-        return [:error, :empty]
-      end
-
-      validated = []
-
-      values.each.with_index do |value, index|
-        case itemspec_validator.call(value)
-        in [:ok, value]  then validated << value
-        in [:error, err] then return [:error, [:array, index, err]]
-        end
-      end
-
-      [:ok, validated]
-    end
-  end
-end

data/lib/explicit/spec/bigdecimal.rb

@@ -1,27 +0,0 @@
-# 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

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-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
-  }.freeze
-
-  ERROR = [:error, :boolean].freeze
-
-  def build(options)
-    lambda do |value|
-      value = VALUES[value]
-
-      return ERROR if value.nil?
-
-      [:ok, value]
-    end
-  end
-end

data/lib/explicit/spec/date_time_iso8601.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require "time"
-
-module Explicit::Spec::DateTimeISO8601
-  extend self
-
-  def call(value)
-    return [:error, :date_time_iso8601] if !value.is_a?(::String)
-
-    timeval = Time.iso8601(value)
-
-    [:ok, timeval]
-  rescue ArgumentError
-    [:error, :date_time_iso8601]
-  end
-end