explicit 0.2.1 → 0.2.4

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

@@ -0,0 +1,87 @@
+<h1
+  class="text-4xl font-bold my-4"
+  id="<%= page.anchor %>"
+  x-intersect="activeLink = '<%= page.anchor %>'"
+>
+  <%= page.title %>
+</h1>
+
+<div class="bg-neutral-800 text-white p-2 rounded font-mono">
+  <% page.request.routes.each do |route| %>
+    <div>
+      <span class="font-bold"><%= route.method.to_s.upcase %></span>
+      
+      <span class="text-neutral-300"><%= page.request.get_base_url %><%= page.request.get_base_path %></span><span class="font-bold"><%= route.path %></span>
+    </div>
+  <% end %>
+</div>
+
+<% if page.request.accepts_file_upload? %>
+  <div class="bg-neutral-800 text-white rounded py-1 px-2 text-sm mt-2 inline-flex items-center gap-2">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="size-5">
+      <path fill-rule="evenodd" d="M8.485 2.495c.673-1.167 2.357-1.167 3.03 0l6.28 10.875c.673 1.167-.17 2.625-1.516 2.625H3.72c-1.347 0-2.189-1.458-1.515-2.625L8.485 2.495ZM10 5a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 10 5Zm0 9a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z" clip-rule="evenodd" />
+    </svg>
+
+    This request requires <span class="font-mono font-bold">multipart/form-data</span> encoding for file upload
+  </div>
+<% end %>
+
+<div class="flex mt-4 gap-8">
+  <div class="page__request space-y-4">
+    <% if (description = page.request.get_description) %>
+      <div class="markdown">
+        <%= Explicit::Documentation::Markdown.to_html(description) %>
+      </div>
+    <% end %>
+
+    <% if page.request.headers.any? %>
+      <div>
+        <div class="bg-gray-100 border-t border-x text-center text-xs p-1 uppercase text-neutral-500">
+          Headers
+        </div>
+
+        <%= type_render page.request.headers_type %>
+      </div>
+    <% end %>
+
+    <% if page.request.params.any? %>
+      <div>
+        <div class="bg-gray-100 border-t border-x text-center text-xs p-1 uppercase text-neutral-500">
+          Params
+        </div>
+
+        <%= type_render page.request.params_type %>
+      </div>
+    <% end %>
+  </div>
+
+  <% statuses = page.request.responses.keys.sort %>
+
+  <div
+    class="page__response"
+    x-data="{ active: <%= statuses.first %> }"
+  >
+    <div class="flex">
+      <% statuses.each do |status| %>
+        <button
+          class="bg-white py-2 px-6"
+          x-bind:class="{ 'border-l border-t border-r -mb-px': active == <%= status %> }"
+          x-on:click="active = <%= status %>"
+        >
+          <span class="text-neutral-400">Resp.</span>
+          <span class="font-bold"><%= status %></span>
+        </button>
+      <% end %>
+    </div>
+
+    <div class="border">
+      <% statuses.each do |status| %>
+        <div class="p-4" x-show="active == <%= status %>">
+          <%= type_render page.request.responses_type(status:) %>
+
+          <%= render partial: "explicit/documentation/request/examples", locals: { request: page.request, status: } %>
+        </div>
+      <% end %>
+    </div>
+  </div>
+</div>

data/app/views/explicit/documentation/request/_examples.html.erb

@@ -0,0 +1,50 @@
+<% examples = request.examples[status] %>
+
+<div
+  class="responses__examples"
+  x-data="{ example: 0, maxsize: <%= examples.size %> }"
+>
+  <% if examples.any? %>
+    <div class="flex items-center -mx-4 my-4 p-4 bg-neutral-100">
+      <div class="text-sm uppercase font-medium tracking-wide text-neutral-600">
+        <% if examples.size > 1 %>
+          Examples (<span x-text="example+1"></span>/<span x-text="maxsize"></span>)
+        <% else %>
+          Example
+        <% end %>
+      </div>
+
+      <% if examples.size > 1 %>
+        <div class="ml-auto flex">
+          <button
+            class="p-1 text-neutral-800 hover:text-black"
+            x-bind:class="{'opacity-30': example === 0}"
+            x-bind:disabled="example === 0"
+            x-on:click="example -= 1"
+          >
+            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="size-6">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M15.75 19.5 8.25 12l7.5-7.5" />
+            </svg>
+          </button>
+
+          <button
+            class="p-1 text-neutral-800 hover:text-black"
+            x-bind:class="{'opacity-30': example === maxsize-1}"
+            x-bind:disabled="example === maxsize-1"
+            x-on:click="example += 1"
+          >
+            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="size-6">
+              <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+            </svg>
+          </button>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+
+  <% request.examples[status].each.with_index do |example, index| %>
+    <% route = request.routes.first %>
+
+    <pre class="font-mono text-sm overflow-auto" x-show="example == <%= index %>"><%= format_request_example(request:, example:) %></pre>
+  <% end %>
+</div>

data/app/views/explicit/documentation/type/_agreement.html.erb

@@ -0,0 +1,7 @@
+The following values are accepted:
+
+<div class="inline-flex flex-wrap gap-2">
+  <% Explicit::Type::Agreement::VALUES.each do |value| %>
+    <code class="font-mono text-xs bg-neutral-200 p-px"><%= value.inspect %></code>
+  <% end %>
+</div>

data/app/views/explicit/documentation/type/_array.html.erb

@@ -0,0 +1,3 @@
+<div class="border divide-y">
+  <%= type_attribute_render name: "Items", type: type.itemtype %>
+</div>

data/app/views/explicit/documentation/type/_big_decimal.html.erb

@@ -0,0 +1,4 @@
+<%= type_constraints do %>
+  <%= type_constraint "min:", type.min if type.min.present? %>
+  <%= type_constraint "max:", type.max if type.max.present? %>
+<% end %>

data/app/views/explicit/documentation/type/_boolean.html.erb

@@ -0,0 +1,7 @@
+The following values are accepted:
+
+<div class="inline-flex flex-wrap gap-2">
+  <% Explicit::Type::Boolean::VALUES.each do |value, _| %>
+    <code class="font-mono text-xs bg-neutral-200 p-px"><%= value.inspect %></code>
+  <% end %>
+</div>

data/app/views/explicit/documentation/type/_date_time_iso8601.html.erb

@@ -0,0 +1,3 @@
+<div class="text-sm">
+  Value must be a valid date time according to ISO 8601. For example: <code>"2024-12-10T14:21:00Z"</code>
+</div>

data/app/views/explicit/documentation/type/_date_time_posix.html.erb

@@ -0,0 +1,3 @@
+<div class="text-sm">
+  Value must be a valid POSIX timestamp. For example: <code>1733923153</code> represents "Dec 11 2024 13:19:13"
+</div>

data/app/views/explicit/documentation/type/_enum.html.erb

@@ -0,0 +1,7 @@
+The following values are accepted:
+
+<div class="inline-flex flex-wrap gap-2">
+  <% type.allowed_values.each do |value, _| %>
+    <code class="font-mono text-xs bg-neutral-200 p-px"><%= value.inspect %></code>
+  <% end %>
+</div>

data/app/views/explicit/documentation/type/_file.html.erb

@@ -0,0 +1,9 @@
+<%= type_constraints do %>
+  <% if type.max_size.present? %>
+    <%= type_constraint "max size:", number_to_human_size(type.max_size, precision: 2) %>
+  <% end %>
+
+  <% if type.content_types.any? %>
+    <%= type_constraint "content types:", type.content_types.join(", ") %>
+  <% end %>
+<% end %>

data/app/views/explicit/documentation/type/_hash.html.erb

@@ -0,0 +1,4 @@
+<div class="border divide-y">
+  <%= type_attribute_render name: "Keys", type: type.keytype %>
+  <%= type_attribute_render name: "Values", type: type.valuetype %>
+</div>

data/app/views/explicit/documentation/type/_integer.html.erb

@@ -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/app/views/explicit/documentation/type/_one_of.html.erb

@@ -0,0 +1,11 @@
+<% type.subtypes.each.with_index do |subtype, index| %>
+  <%= type_render subtype %>
+
+  <% if index < type.subtypes.size - 1 %>
+    <div class="flex items-center my-4">
+      <div class="h-px w-full flex-grow bg-neutral-200"></div>
+      <div class="mx-4 text-neutral-400 text-xs">OR</div>
+      <div class="h-px w-full flex-grow bg-neutral-300"></div>
+    </div>
+  <% end %>
+<% end %>

data/app/views/explicit/documentation/type/_record.html.erb

@@ -0,0 +1,9 @@
+<div class="border divide-y">
+  <% if type.attributes.empty? %>
+    <div class="p-4 text-neutral-400 text-center text-sm">--Empty body--</div>
+  <% end %>
+
+  <% type.attributes.each do |name, type| %>
+    <%= type_attribute_render(name:, type:) %>
+  <% end %>
+</div>

data/app/views/explicit/documentation/type/_string.html.erb

@@ -0,0 +1,21 @@
+<%= type_constraints do %>
+  <% if type.empty == false %>
+    <%= type_constraint "not", "empty" %>
+  <% end %>
+
+  <% if type.minlength %>
+    <%= type_constraint "minlength", type.minlength %>
+  <% end %>
+
+  <% if type.maxlength %>
+    <%= type_constraint "maxlength", type.maxlength %>
+  <% end %>
+
+  <% if type.format %>
+    <%= type_constraint "format", type.format.inspect %>
+  <% end %>
+
+  <% if type.downcase %>
+    <%= type_constraint "case", "insensitive" %>
+  <% end %>
+<% end %>

data/config/locales/en.yml

@@ -6,21 +6,37 @@ en:
       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"
-      hash: "must be a map"
+      date_time_posix: "must be a valid posix timestamp"
+      hash: "must be an object"
       hash_key: "invalid key (%{key}): %{error}"
       hash_value: "invalid value at key (%{key}): %{error}"
-      inclusion: "must be one of: %{values}"
+      enum: "must be one of: %{allowed_values}"
+      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}"
       integer: "must be an integer"
-      min: "must be bigger than or equal to %{min}"
-      max: "must be smaller than or equal to %{max}"
-      negative: "must not be negative"
-      positive: "must not be positive"
+      min: "must be at least %{min}"
+      max: "must be at most %{max}"
+      not_negative: "must not be negative"
+      not_positive: "must not be positive"
       literal: "must be %{value}"
       string: "must be a string"
       empty: "must not be empty"
-      minlength: "length must be greater than or equal to %{minlength}"
-      maxlength: "length must be smaller than or equal to %{maxlength}"
+      minlength: "length must be at least %{minlength}"
+      maxlength: "length must be at most %{maxlength}"
       format: "must have format %{regex}"
-    documentation:
-      params_header: Request params
+    swagger:
+      agreement: "* Must be accepted (true)"
+      big_decimal_min: "* Minimum: %{min}"
+      big_decimal_max: "* Maximum: %{max}"
+      date_time_iso8601: "* Must be valid according to ISO 8601"
+      date_time_posix: "* POSIX time or Unix epoch is the amount of seconds since 1970-01-01"
+      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"
+      string_not_empty: "* Must not be empty"
+      string_downcase: "* Case insensitive"

data/lib/explicit/configuration.rb

@@ -17,7 +17,7 @@ module Explicit
     end
 
     def request_examples_persistance_enabled?
-      ENV["EXPLICIT_PERSIST_EXAMPLES"].in? %w[true 1 on]
+      ENV["UPDATE_REQUEST_EXAMPLES"].in? %w[true 1 on ok]
     end
 
     def rescue_from_invalid_params=(enabled)

data/lib/explicit/documentation/builder.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Explicit::Documentation
+  class Builder
+    attr_reader :rails_engine, :sections, :swagger, :webpage
+
+    def initialize(rails_engine)
+      @rails_engine = rails_engine
+      @sections = []
+      @current_section = nil
+      @version = "1.0"
+      @swagger = Output::Swagger.new(self)
+      @webpage = Output::Webpage.new(self)
+    end
+
+    def page_title(text) = (@page_title = text)
+    def get_page_title = @page_title
+
+    def company_logo_url(url) = (@company_logo_url = url)
+    def get_company_logo_url = @company_logo_url
+
+    def version(version) = (@version = version)
+    def get_version = @version
+
+    def section(name, &block)
+      @current_section = Section.new(name:, pages: [])
+
+      block.call
+
+      @sections << @current_section
+
+      @current_section = nil
+    end
+
+    def requests
+      @sections.flat_map(&:pages).filter(&:request?).map(&:request)
+    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 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)
+
+      requests.each do |request|
+        examples[request.gid]&.each do |example|
+          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
+    rescue JSON::ParserError
+      ::Rails.logger.error("[Explicit] Could not parse JSON in request examples file at #{Explicit.configuration.request_examples_file_path}")
+    end
+  end
+end

data/lib/explicit/documentation/markdown.rb

@@ -3,19 +3,8 @@
 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: {
+  def to_html(markdown_text)
+    ::Commonmarker.to_html(markdown_text, options: {
       parse: { smart: true },
       render: { hardbreaks: false }
     }).html_safe

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Explicit::Documentation::Output
+  class Swagger
+    InconsistentBasePathError = Class.new(RuntimeError)
+    InconsistentBaseURLError = Class.new(RuntimeError)
+
+    attr_reader :builder
+
+    def initialize(builder)
+      @builder = builder
+    end
+
+    def swagger_document
+      {
+        openapi: "3.0.1",
+        info: {
+          title: builder.get_page_title,
+          version: builder.get_version
+        },
+        servers: [
+          {
+            url: get_base_url
+          }
+        ],
+        tags: build_tags_from_sections,
+        paths: build_paths_from_requests
+      }
+    end
+
+    def call(request)
+      @swagger_document ||= swagger_document
+
+      [200, {"Content-Type" => "application/json"}, [@swagger_document.to_json]]
+    end
+
+    private
+      def get_base_url
+        base_urls = builder.requests.map(&:get_base_url).uniq
+        base_paths = builder.requests.map(&:get_base_path).uniq
+
+        if !base_urls.one?
+          raise InconsistentBaseURLError.new <<~TXT
+            There are requests with different base URLs in the same documentation,
+            which is not supported by Swagger.
+
+            The following base URLs are present:
+
+              #{base_urls.join("\n  ")}
+
+            Please make sure all requests have the same base URL.
+          TXT
+        end
+
+        if !base_paths.one?
+          raise InconsistentBasePathError.new <<~TXT
+            There are requests with different base paths in the same documentation,
+            which is not supported by Swagger.
+
+            The following base paths are present:
+
+              #{base_paths.join("\n  ")}
+
+            Please make sure all requests have the same base path.
+          TXT
+        end
+
+        base_urls.first + base_paths.first
+      end
+
+      def build_tags_from_sections
+        builder.sections.filter(&:contains_request?).map do |section|
+          { name: section.name }
+        end
+      end
+
+      def build_paths_from_requests
+        paths = Hash.new { |hash, key| hash[key] = {} }
+
+        builder.sections.filter(&:contains_request?).each do |section|
+          section.pages.filter(&:request?).each do |page|
+            request = page.request
+            route = request.routes.first
+
+            paths[route.path_with_curly_syntax][route.method.to_s] = {
+              tags: [section.name],
+              summary: request.get_title,
+              description: request.get_description,
+              parameters: build_parameters(request),
+              requestBody: build_request_body(request),
+              responses: build_responses(request)
+            }.compact_blank
+          end
+        end
+
+        paths
+      end
+
+      def build_parameters(request)
+        headers =
+          request.headers_type.attributes.map do |name, type|
+            {
+              name: name.to_s,
+              in: "header",
+              required: type.required?,
+              schema: type.swagger_schema,
+              style: "simple"
+            }
+          end
+
+        path_params =
+          request.params_type.path_params_type.attributes.map do |name, type|
+            {
+              name: name.to_s,
+              in: "path",
+              required: type.required?,
+              schema: type.swagger_schema,
+              style: "simple"
+            }
+          end
+
+        headers + path_params
+      end
+
+      def build_request_body(request)
+        body_params_type = request.params_type.body_params_type
+        content_type = request.accepts_file_upload? ? "multipart/form-data" : "application/json"
+
+        return nil if body_params_type.attributes.empty?
+
+        examples = 
+          request.examples
+            .flat_map { |_, examples| examples }
+            .filter_map do |example|
+              case body_params_type.validate(example.params)
+              in [:ok, validated_data] then validated_data
+              in [:error, _] then nil
+              end
+            end
+            .map.with_index { |example, index| [index, { value: example }] }
+            .to_h
+
+        {
+          content: {
+            content_type => {
+              schema: body_params_type.swagger_schema,
+              examples:
+            }.compact_blank
+          },
+          required: body_params_type.attributes.any?
+        }
+      end
+
+      def build_responses(request)
+        responses = {}
+
+        request.responses.each do |status, _|
+          examples = request.examples[status].map.with_index do |example, index|
+            [index.to_s, { value: example.response.data }]
+          end.to_h
+
+          responses[status] = {
+            content: {
+              "application/json" => {
+                schema: request.responses_type(status:).swagger_schema,
+                examples: examples
+              }.compact_blank
+            },
+            description: Rack::Utils::HTTP_STATUS_CODES[status]
+          }
+        end
+
+        responses
+      end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Explicit::Documentation::Output
+  class Webpage
+    attr_reader :builder
+
+    def initialize(builder)
+      @builder = builder
+    end
+
+    def call(request)
+      @html ||= render_documentation_page
+
+      [200, {}, [@html]]
+    end
+
+    private
+      def render_documentation_page
+        Explicit::ApplicationController.render(
+          partial: "explicit/documentation/page",
+          locals: {
+            url_helpers: @builder.rails_engine.routes.url_helpers,
+            page_title: builder.get_page_title,
+            company_logo_url: builder.get_company_logo_url,
+            version: builder.get_version,
+            sections: builder.sections,
+          }
+        )
+      end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Explicit::Documentation::Page
+  class Partial
+    attr_reader :title, :partial
+
+    def initialize(title:, partial:)
+      @title = title
+      @partial = partial
+    end
+
+    def request?
+      false
+    end
+
+    def anchor
+      title.gsub(" ", "-").downcase
+    end
+  end
+end