explicit 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0ccbe69649ce5ca8fac5e0419943c1357206950a3436e279670cb62f5a359fe
-  data.tar.gz: 556861f1b18e7b900753ddc3aba962501a4991047dae5e1260a120d7de6c15e7
+  metadata.gz: 5adb170708747adfb160afcf5c4248892418ec518302defa17c692fa34f4cfff
+  data.tar.gz: 10258e426028dcbce19a9825b5541edc75d5e288c8846f7d21f36f2a239ce9b8
 SHA512:
-  metadata.gz: 50d01f40937fe47d381d5807bc823b1abbb63e6929a09215da81167bad53276e96584ee581ff945eebf25568ca57c3234827102ab0e73fb4cfc62eb846631d3a
-  data.tar.gz: 4219bebcffce9aac144a739137aa3670f036f7224991fda4acc2db973cc8f11fa25532c604c9c26bf164cb77a3dc18174605b589b0afe9fe031a8ceee67bd1b9
+  metadata.gz: 86e5c040ecc814b16d6a8b7b43d9f7b6ee4764a36b5b21e56d504cde8f7229db0ffa1a2eb66e7c2621f8c1a2a453d59823577bf17bac2485551f0ed567b6edb0
+  data.tar.gz: a246c4136d476c61ef8bb59cd09b904918f2ec01ac4812862a6a02f6d051d7982e0ba37bc9577b6d045bb9c39185f274c535c0b9f3e7cfceb21671663117dc68

data/README.md

@@ -1,16 +1,18 @@
 # Explicit
 
-Explicit is a validation and documentation library for JSON APIs that enforces
-documented specs at runtime.
+Explicit is a validation and documentation library for REST APIs that enforces
+documented types at runtime.
+
+![Documentation example screenshot](https://raw.githubusercontent.com/luizpvas/explicit/refs/heads/main/assets/webapp_screenshot.png)
 
 1. [Installation](#installation)
 2. [Defining requests](#defining-requests)
-3. [Reusing specs](#reusing-specs)
+3. [Reusing types](#reusing-types)
 4. [Reusing requests](#reusing-requests)
 5. [Writing tests](#writing-tests)
 6. [Publishing documentation](#publishing-documentation)
    - [Adding request examples](#adding-request-examples)
-7. Specs
+7. Types
    - [Agreement](#agreement)
    - [Array](#array)
    - [BigDecimal](#bigdecimal)
@@ -19,8 +21,9 @@ documented specs at runtime.
    - [Date Time Posix](#date-time-posix)
    - [Default](#default)
    - [Description](#description)
+   - [Enum](#enum)
+   - [File](#file)
    - [Hash](#hash)
-   - [Inclusion](#inclusion)
    - [Integer](#integer)
    - [Literal](#literal)
    - [Nilable](#nilable)
@@ -31,7 +34,6 @@ documented specs at runtime.
    - [Changing examples file path](#changing-examples-file-path)
    - [Customizing error messages](#customizing-error-messages)
    - [Customizing error serialization](#customizing-error-serialization)
-9. [Performance benchmark](#performance-benchmark)
 
 # Installation
 
@@ -53,10 +55,10 @@ 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, spec)` - Adds a spec to the request header.
-- `param(name, spec, options = {})` - Adds a spec to the request param.
+- `header(name, type)` - Adds a type to the request header.
+- `param(name, type, options = {})` - Adds a type to the request param.
   It works for params in the request body, query string and path params.
-- `response(status, spec)` - Adds a response spec. You can add multiple
+- `response(status, type)` - Adds a response type. You can add multiple
   responses with different formats.
 - `add_example(params:, headers:, response:)` - Adds an example to the
   documentation. [See more details here](#adding-request-examples).
@@ -72,14 +74,14 @@ class RegistrationsController < ActionController::API
   Request = Explicit::Request.new do
     post "/api/registrations"
 
-    description <<-MD
+    description <<~MD
     Attempts to register a new user in the system. If `payment_type` is not
     specified a trial period of 30 days is started.
     MD
 
     param :name, [:string, empty: false]
     param :email, [:string, format: URI::MailTo::EMAIL_REGEXP, strip: true]
-    param :payment_type, [:inclusion, ["free_trial", "credit_card"]], default: "free_trial"
+    param :payment_type, [:enum, ["free_trial", "credit_card"]], default: "free_trial"
     param :terms_of_use, :agreement
 
     response 200, { user: { id: :integer, email: :string } }
@@ -98,13 +100,13 @@ class RegistrationsController < ActionController::API
 end
 ```
 
-# Reusing specs
+# Reusing types
 
-Specs are just data. You can share specs the same way you reuse constants or
+Types are just data. You can share types the same way you reuse constants or
 configs in your app. For example:
 
 ```ruby
-module MyApp::Spec
+module MyApp::Type
   UUID = [:string, format: /^\h{8}-(\h{4}-){3}\h{12}$/].freeze
   EMAIL = [:string, format: URI::MailTo::EMAIL_REGEXP, strip: true].freeze
 
@@ -114,11 +116,11 @@ module MyApp::Spec
   }.freeze
 end
 
-# ... and then reference the shared specs when needed
+# ... and then reference the shared types when needed
 Request = Explicit::Request.new do
-  param :customer_uuid, MyApp::Spec::UUID
-  param :email, MyApp::Spec::EMAIL
-  param :address, MyApp::Spec::ADDRESS
+  param :customer_uuid, MyApp::Type::UUID
+  param :email, MyApp::Type::EMAIL
+  param :address, MyApp::Type::ADDRESS
 end
 ```
 
@@ -147,7 +149,7 @@ end
 Include `Explicit::TestHelper` in your `test/test_helper.rb` or
 `spec/rails_helper.rb`. This module provides the method
 `fetch(request, **options)` that let's you verify the endpoint works as
-expected and that it responds with a valid response according to the spec.
+expected and that it responds with a valid response according to the docs.
 
 <details open>
   <summary>For Minitest users, add the following line to your <code>test/test_helper.rb</code></summary>
@@ -179,8 +181,8 @@ end
 </details>
 
 To test your controller, call `fetch(request, **options)` and write
-assertions against the response. If the response is invalid according to the
-spec the test fails with `Explicit::Request::InvalidResponseError`.
+assertions against the response. If the response is invalid the test fails with
+`Explicit::Request::InvalidResponseError`.
 
 The response object has a `status`, an integer value for the http status, and
 `data`, a hash with the response data. It also provides `dig` for a
@@ -190,7 +192,7 @@ slighly shorter syntax when accessing nested attributes.
 > `put "/customers/:customer_id"` you must call as
 > `fetch(CustomerController::UpdateRequest, { customer_id: 123 })`.
 
-> Note: Response specs are only verified in test environment with no
+> Note: Response types are only verified in test environment with no
 > performance penalty when running in production.
 
 <details open>
@@ -243,6 +245,8 @@ Call `Explicit::Documentation.new` to group, organize and publish the
 documentation for your API. The following methods are available:
 
 - `page_title(text)` - Sets the web page title.
+- `company_logo_url(url)` - Shows the company logo above the navigation menu.
+- `version(semver)` - Sets the version of the API. Default: "1.0"
 - `section(name, &block)` - Adds a section to the navigation menu.
 - `add(request)` - Adds a request to the section
 - `add(title:, partial:)` - Adds a partial to the section
@@ -253,6 +257,8 @@ For example:
 module MyApp::API::V1
   Documentation = Explicit::Documentation.new do
     page_title "Acme API Docs"
+    company_logo_url "https://my-app.com/logo.png"
+    version "1.0.5"
 
     section "Introduction" do
       add title: "About", partial: "api/v1/introduction/about"
@@ -293,7 +299,7 @@ You can add request examples in two different ways:
 
 In a request, call `add_example(params:, headers:, response:)` after declaring
 params and responses. It's important the example comes after params and
-responses to make sure it actually follows the spec.
+responses to make sure it actually follows the type definition.
 
 For example:
 
@@ -360,37 +366,36 @@ end
 ```
 
 Whenever you wish to refresh the examples file run the test suite with the ENV
-`EXPLICIT_PERSIST_EXAMPLES` set. For example
-`EXPLICIT_PERSIST_EXAMPLES=true bin/rails test` or
-`EXPLICIT_PERSIST_EXAMPLES=true bundle exec rspec`. The examples file is located
-at `#{Rails.root}/public/explicit_request_examples.json` by default, but you can
+`UPDATE_REQUEST_EXAMPLES` set. For example
+`UPDATE_REQUEST_EXAMPLES=true bin/rails test` or
+`UPDATE_REQUEST_EXAMPLES=true bundle exec rspec`. The file is located at
+`#{Rails.root}/public/explicit_request_examples.json` by default, but you can
 [change it here](#request-examples-file-path).
 
 **Important: be careful not to leak any sensitive data when persisting
 examples from tests**
 
-# Specs
+# Types
 
 ### Agreement
 
 ```ruby
 :agreement
-[:agreement, parse: true]
 ```
 
 A boolean that must always be true. Useful for terms of use or agreement
-acceptances. If `parse: true` is specified then the following
-values are accepted: `true`, `"true"`, `"on"`, `"1"` and `1`.
+acceptances. The following values are accepted: `true`, `"true"`, `"on"`, `"1"`
+and `1`.
 
 ### Array
 
 ```ruby
-[:array, subspec, options = {}]
+[:array, subtype, options = {}]
 [:array, :string]
 [:array, :integer, empty: false]
 ```
 
-All items in the array must be valid according to the subspec. If at least one
+All items in the array must be valid according to the subtype. If at least one
 value is invalid then the array is invalid.
 
 ### BigDecimal
@@ -402,19 +407,16 @@ value is invalid then the array is invalid.
 ```
 
 Value must be an integer or a string like `"0.2"` to avoid rounding errors.
-
 [Reference](https://ruby-doc.org/stdlib-3.1.0/libdoc/bigdecimal/rdoc/BigDecimal.html)
 
 ### Boolean
 
 ```ruby
 :boolean
-[:boolean, parse: true]
 ```
 
-If `parse: true` is specified then the following values are converted to `true`:
-`"true"`, `"on"`, `"1"` and `1`, and the following values are converted to
-`false`: `"false"`, `"off"`, `"0"` and `0`.
+The following values are true: `true`, `"true"`, `"on"`, `"1"` and `1`, and the
+following values are false: `false`, `"false"`, `"off"`, `"0"` and `0`.
 
 ### Date Time ISO8601
 
@@ -437,7 +439,7 @@ example: `1733923153`
 ### Default
 
 ```ruby
-[:default, default_value, subspec]
+[:default, default_value, subtype]
 [:default, "USD", :string]
 [:default, 0, :integer]
 [:default, -> { Time.current.iso8601 }, :date_time_iso8601]
@@ -453,52 +455,59 @@ called.
 ### Description
 
 ```ruby
-[:description, markdown_text, subspec]
+[:description, markdown_text, subtype]
 [:description, "Customer full name", :string]
 [:description, "Rating score from 0 (bad) to 5 (good)", :integer]
 ```
 
-Adds a description to the spec. Descriptions are displayed in documentation
+Adds a description to the type. Descriptions are displayed in documentation
 and do not affect validation in any way with. There is no overhead at runtime.
 Markdown supported.
 
 ### Hash
 
 ```ruby
-[:hash, keyspec, valuespec, options = {}]
+[:hash, keytype, valuetype, options = {}]
 [:hash, :string, :string]
 [:hash, :string, :integer]
 [:hash, :string, :integer, empty: false]
 [:hash, :string, [:array, :date_time_iso8601]]
 ```
 
-Hashes are key value pairs where all keys must match keyspec and all values must
-match valuespec. If you are expecting a hash with a specific set of keys use a
+Hashes are key value pairs where all keys must match keytype and all values must
+match valuetype. If you are expecting a hash with a specific set of keys use a
 [record](#record) instead.
 
-### Inclusion
+### Enum
 
 ```ruby
-[:inclusion, allowed_values]
-[:inclusion, ["user", "admin"]]
-[:inclusion, [10, 20, 30, 40, 50]]
+[:enum, allowed_values]
+[:enum, ["user", "admin"]]
+[:enum, [10, 20, 30, 40, 50]]
 ```
 
-Value must be present in the set of allowed values.
+### File
+
+```ruby
+:file
+[:file, max_size: 2.megabytes]
+[:file, content_types: %w[image/png image/jpeg]]
+```
+
+Value must be an uploaded file using "multipart/form-data" encoding.
 
 ### Integer
 
 ```ruby
 :integer
-[:integer, parse: true]
 [:integer, negative: false]
 [:integer, positive: false]
 [:integer, min: 0] # inclusive
 [:integer, max: 10] # inclusive
 ```
 
-If `parse: true` is specified then integer encoded string values such as "10" or
-"-2" are automatically converted to integer.
+Integer encoded string values such as "10" or "-2" are automatically converted
+to integer.
 
 ### Literal
 
@@ -506,48 +515,48 @@ If `parse: true` is specified then integer encoded string values such as "10" or
 [:literal, value]
 [:literal, 6379]
 [:literal, "value"]
-"value" # strings work like a literal specs, so you can use this shorter syntax.
+"value" # strings are literal types, so you can use the shorter syntax.
 ```
 
-A literal value behaves similar to inclusion with a single value. Useful for
-matching against multiple specs in [`one_of`](#one-of).
+A literal value behaves similar to an enum with a single value. Useful for
+matching against multiple types in [`one_of`](#one-of).
 
 ### Nilable
 
 ```ruby
-[:nilable, subspec]
+[:nilable, subtype]
 [:nilable, :string]
 [:nilable, [:array, :integer]]
 ```
 
-Value must either match the subspec or be nil.
+Value must either match the subtype or be nil.
 
 ### One of
 
 ```ruby
-[:one_of, spec1, spec2, ..., specN]
+[:one_of, type1, type2, ..., typeN]
 [:one_of, :string, :integer]
 [:one_of, { email: :string }, { phone_number: :string }]
 ```
 
-Attempts to validate against each spec in order stopping at the first spec that
-successfully matches the value. If none of the specs match, an error is
+Attempts to validate against each type in order stopping at the first type that
+successfully matches the value. If none of the types match, an error is
 returned.
 
 ### Record
 
 ```ruby
-user_spec = {
+user_type = {
   name: :string,
   email: [:string, format: URI::MailTo::EMAIL_REGEXP]
 }
 
-address_spec = {
+address_type = {
   country_name: :string,
   zipcode: [:string, { format: /\d{6}-\d{3}/, strip: true }]
 }
 
-payment_spec = {
+payment_type = {
   currency: [:nilable, :string], # use :nilable for optional attribute
   amount: :bigdecimal
 }
@@ -561,8 +570,9 @@ records with array of records, etc.
 
 ```ruby
 :string
-[:string, strip: true]
+[:string, strip: true] # " foo " gets transformed to "foo"
 [:string, empty: false]
+[:string, downcase: true] # "FOO" gets transformed to "foo"
 [:string, format: URI::MailTo::EMAIL_REGEXP]
 [:string, minlength: 8] # inclusive
 [:string, maxlength: 20] # inclusive
@@ -604,9 +614,7 @@ your base controller. Use the following code as a starting point:
 ```ruby
 class ApplicationController < ActionController::API
   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
 ```

data/app/helpers/explicit/application_helper.rb

@@ -2,5 +2,37 @@
 
 module Explicit
   module ApplicationHelper
+    def type_render(type)
+      render partial: type.partial, locals: { type: }
+    end
+
+    def type_attribute_render(name:, type:)
+      render partial: "explicit/documentation/attribute", locals: { name:, type: }
+    end
+
+    def type_constraints(&block)
+      content_tag(:div, class: "flex flex-wrap gap-2", &block)
+    end
+
+    def type_constraint(name, value)
+      content_tag(:div, class: "bg-neutral-200 px-1 text-sm") do
+        content_tag(:span, name) + " " + content_tag(:span, value)
+      end
+    end
+
+    def type_has_details?(type)
+      type.description.present? || type.has_details?
+    end
+
+    def format_request_example(request:, example:)
+      line_break = '<span class="text-white">\</span>'
+
+      <<~BASH.html_safe
+      #{example.to_curl_lines.join(" #{line_break}\n")}
+
+      # #{example.response.status} #{Rack::Utils::HTTP_STATUS_CODES[example.response.status]}
+      #{JSON.pretty_generate(example.response.data)}
+      BASH
+    end
   end
 end

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

@@ -0,0 +1,38 @@
+<div class="p-3" x-data="{ expanded: false }">
+  <div class="flex items-center gap-2" x-on:click="expanded = !expanded">
+    <span class="font-mono font-bold">
+      <%= name %>
+    </span>
+
+    <span class="text-sm text-neutral-500">
+      <%= type.summary %>
+    </span>
+
+    <% if type.param_location_path? %>
+      <span class="bg-neutral-800 text-white text-xs font-bold rounded px-1">in URL</span>
+    <% end %>
+
+    <% if type.has_details? || type.description.present? %>
+      <div class="record__summary__expand">
+        <span x-show="expanded">&#9650;</span>
+        <span x-show="!expanded">&#9660;</span>
+      </div>
+    <% end %>
+  </div>
+
+  <% if type.has_details? || type.description.present? %>
+    <div class="mt-2" x-show="expanded">
+      <% if (description = type.description) %>
+        <div class="text-neutral-600 markdown">
+          <%= Explicit::Documentation::Markdown.to_html(description) %>
+        </div>
+      <% end %>
+
+      <% if type.has_details? %>
+        <div class="record__subtype">
+          <%= type_render type %>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+</div>

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

@@ -0,0 +1,166 @@
+<!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-50: #fafafa;
+      --color-neutral-100: #f5f5f5;
+      --color-neutral-200: #e5e5e5;
+      --color-neutral-300: #d4d4d8;
+      --color-neutral-400: #a3a3a3;
+      --color-neutral-500: #737373;
+      --color-neutral-600: #525252;
+    }
+
+    .page:not(:first-of-type) {
+      border-top: 1px solid var(--color-neutral-200);
+    }
+    .page__url {
+      background: var(--color-neutral-100);
+      border: 1px solid var(--color-neutral-300);
+      font-family: monospace;
+      padding: 0.8rem;
+    }
+    .page__url__shared {
+      color: var(--color-neutral-500);
+    }
+    .page__url__path {
+      font-weight: bold;
+    }
+    .page__container {
+      display: flex;
+      gap: 1rem;
+      margin-top: 1rem;
+    }
+    .page__request {
+      width: 50%;
+    }
+    .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;
+    }
+    .markdown ul {
+      list-style-type: disc;
+    }
+    .markdown li {
+      margin-left: 2rem;
+    }
+
+    .record__param {
+      padding: 0.8rem;
+    }
+    .record__param:not(:last-of-type) {
+      border-bottom: 1px solid var(--color-neutral-200);
+    }
+    .record__summary {
+      display: flex;
+      align-items: end;
+      gap: 1rem;
+    }
+    .record__summary__expand {
+      margin-left: auto;
+      color: var(--color-neutral-400);
+    }
+    .record__constraint {
+      font-size: 12px;
+      background: var(--color-neutral-200);
+      padding: 1px 4px;
+      border-radius: 1px;
+    }
+    .record__subtype {
+      margin-top: 0.5rem;
+    }
+
+    .responses__tabs {
+      display: flex;
+    }
+    .responses__tab {
+      padding: 10px;
+    }
+    .responses__tab.active {
+      border-left: 1px solid var(--color-neutral-300);
+      border-top: 1px solid var(--color-neutral-300);
+      border-right: 1px solid var(--color-neutral-300);
+      border-bottom: 1px solid #FFF;
+      margin-bottom: -1px;
+    }
+    .responses__types {
+      border: 1px solid var(--color-neutral-300);
+    }
+  </style>
+
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/intersect@3.x.x/dist/cdn.min.js"></script>
+  <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
+</head>
+
+<body>
+  <div class="flex" x-data="{ activeLink: null }">
+    <section class="bg-neutral-100 border-r w-[280px] shrink-0 h-screen overflow-y-auto">
+      <% if company_logo_url.present? %>
+        <div class="flex items-center justify-center mt-4 mb-8">
+          <img src="<%= company_logo_url %>" class="max-w-full h-auto" />
+        </div>
+      <% end %>
+
+      <div class="text-center text-xs border-y mb-4 flex divide-x">
+        <div class="p-1 text-neutral-500 w-1/2">
+          Version <%= version %>
+        </div>
+        <div class="p-1 w-1/2">
+          <%= link_to url_helpers.explicit_documentation_swagger_path, target: "_blank", class: "flex items-center justify-center gap-1 text-neutral-900" do %>
+            <span>Swagger</span>
+
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" class="size-4">
+              <path d="M6.22 8.72a.75.75 0 0 0 1.06 1.06l5.22-5.22v1.69a.75.75 0 0 0 1.5 0v-3.5a.75.75 0 0 0-.75-.75h-3.5a.75.75 0 0 0 0 1.5h1.69L6.22 8.72Z" />
+              <path d="M3.5 6.75c0-.69.56-1.25 1.25-1.25H7A.75.75 0 0 0 7 4H4.75A2.75 2.75 0 0 0 2 6.75v4.5A2.75 2.75 0 0 0 4.75 14h4.5A2.75 2.75 0 0 0 12 11.25V9a.75.75 0 0 0-1.5 0v2.25c0 .69-.56 1.25-1.25 1.25h-4.5c-.69 0-1.25-.56-1.25-1.25v-4.5Z" />
+            </svg>
+          <% end %>
+        </div>
+      </div>
+
+      <div class="space-y-4" >
+        <% sections.each do |section| %>
+          <details class="px-4" open>
+            <summary class="font-bold"><%= section.name %></summary>
+
+            <% section.pages.each do |page| %>
+              <%= link_to page.title,
+                    "##{page.anchor}",
+                    class: "block pl-4 hover:bg-neutral-200",
+                    "x-bind:class" => "{ 'bg-neutral-200': activeLink == '#{page.anchor}' }" %>
+            <% end %>
+          </details>
+        <% end %>
+      </div>
+    </section>
+
+    <main class="relative grow h-screen overflow-auto">
+      <% sections.each do |section| %>
+        <% section.pages.each do |page| %>
+          <div class="p-8 border-t">
+            <%= render partial: page.partial, locals: { page: } %>
+          </div>
+        <% end %>
+      <% end %>
+    </main>
+  </div>
+</body>
+</html>