explicit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdfcf17daab19ff8c25fa77a72b8e7d7bf085ee98726f898c7bc74819accda49
-  data.tar.gz: 2409883f725d14e47afc8509c3083c3e014713053b91b72bc48d13c1f1ea0b16
+  metadata.gz: 3dd0ae09016ab5f9efdb05b3b4e7ec68f8c824bbb9fcbe347d3e277ee5f8ae9e
+  data.tar.gz: 14d778db7346642da91f253ab53e39471de8e3a4c23e7647cc3803af3961a138
 SHA512:
-  metadata.gz: e50376405bd6f2305de7716df8f414f26fc4b660999ec673bc9f20f54d41ccd06f535704c382ab2f636b789db34ba1b39f7929cce974dfb3440b16aa4f53e774
-  data.tar.gz: 5a6c7fb91762aff2a883165288b2a4d3a6caa5058a243a185c82fa9a4e9acf14fa8db68a3bba7a43aff3935a936f954ff86f46c5c49845ec930515a4f60b2741
+  metadata.gz: 5e6d8e4c26483a1e04376956588f220fd6a5442c008a8193c96fececc2b9f4ad2a73ffcb49c9bad22757e7d21237599fcdda977a96bdc204bc8b7f194c7c102c
+  data.tar.gz: cd4801c48e82ac2683b3b2a1118f2e908f0189adb975fbe38d49210615463963d8fb0e45afb22e9fde8cba6b21a0d14fb0898d35dab58755137c963994dd8c38

data/README.md

@@ -1,21 +1,24 @@
 # Explicit
 
 Explicit is a validation and documentation library for JSON APIs that enforces
-documented specs during runtime.
+documented specs at runtime.
 
 1. [Installation](#installation)
 2. [Defining requests](#defining-requests)
 3. [Reusing specs](#reusing-specs)
-4. [Writing tests](#writing-tests)
-5. [Writing documentation](#writing-documentation)
-6. [Performance benchmark](#performance-benchmark)
+4. [Reusing requests](#reusing-requests)
+5. [Writing tests](#writing-tests)
+6. [Publishing documentation](#publishing-documentation)
+   - [Adding request examples](#adding-request-examples)
 7. Specs
    - [Agreement](#agreement)
    - [Array](#array)
+   - [BigDecimal](#bigdecimal)
    - [Boolean](#boolean)
    - [Date Time ISO8601](#date-time-iso8601)
    - [Date Time Posix](#date-time-posix)
    - [Default](#default)
+   - [Description](#description)
    - [Hash](#hash)
    - [Inclusion](#inclusion)
    - [Integer](#integer)
@@ -24,9 +27,11 @@ documented specs during runtime.
    - [One of](#one-of)
    - [Record](#record)
    - [String](#string)
-8. Advanced configuration
+8. [Configuration](#configuration)
+   - [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
 
@@ -38,26 +43,33 @@ gem "explicit", "~> 0.1"
 
 # Defining requests
 
-You define request specs by inheriting from `Explicit::Request`. The following
-methods are available:
+Call `Explicit::Request.new` to define a request. The following methods are
+available:
 
-- `get(path)` - Adds a route to the request. Use the syntax `:param` for path
-  params. For example: `get "/customers/:customer_id"`.
+- `get(path)` - Adds a route to the request. Use the syntax `/:param` for path
+  params.
   - There is also `head`, `post`, `put`, `delete`, `options` and `patch` for
     other HTTP verbs.
-- `title(text)` - Adds a title to the request. Displayed in the documentation.
-- `description(text)` - Adds a description to the endpoint. Markdown supported.
-- `header(name, spec)` - Adds a header to the endpoint.
-- `param(name, spec, options = {})` - Adds the request param to the endpoint.
+- `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.
   It works for params in the request body, query string and path params.
 - `response(status, spec)` - Adds a response spec. 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).
+- `base_url(url)` - Sets the host for this API. For example: "https://api.myapp.com".
+  Meant to be used with [request composition](#reusing-requests).
+- `base_path(prefix)` - Sets a prefix for the routes. For example: "/api/v1".
+  Meant to be used with [request composition](#reusing-requests).
 
 For example:
 
 ```ruby
 class RegistrationsController < ActionController::API
-  class Request < Explicit::Request
+  Request = Explicit::Request.new do
     post "/api/registrations"
 
     description <<-MD
@@ -79,7 +91,7 @@ class RegistrationsController < ActionController::API
 
     user = User.create!(name:, email:, payment_type:)
 
-    render json: user: { user.as_json(:id, :email) }
+    render json: { user: user.as_json(only: %[id email]) }
   rescue ActiveRecord::RecordNotUnique
     render json: { error: "email_already_taken" }, status: 422
   end
@@ -88,7 +100,7 @@ end
 
 # Reusing specs
 
-Specs are just data. You can reuse specs the same way you reuse constants or
+Specs are just data. You can share specs the same way you reuse constants or
 configs in your app. For example:
 
 ```ruby
@@ -97,27 +109,48 @@ module MyApp::Spec
   EMAIL = [:string, format: URI::MailTo::EMAIL_REGEXP, strip: true].freeze
 
   ADDRESS = {
-    country_name: :string,
+    country_name: [:string, empty: false],
     zipcode: [:string, format: /\d{6}-\d{3}/]
   }.freeze
 end
 
 # ... and then reference the shared specs when needed
-class Request < Explicit::Request
+Request = Explicit::Request.new do
   param :customer_uuid, MyApp::Spec::UUID
   param :email, MyApp::Spec::EMAIL
   param :address, MyApp::Spec::ADDRESS
 end
 ```
 
+# Reusing requests
+
+Sometimes it is useful to share a group of params, headers or responses between
+requests. You can achieve this by instantiating requests from an existing
+request instead of `Explicit::Request`. For example:
+
+```ruby
+AuthenticatedRequest = Explicit::Request.new do
+  header "Authorization", [:string, format: /Bearer [a-zA-Z0-9]{20}/]
+
+  response 403, { error: "unauthorized" }
+end
+
+Request = AuthenticatedRequest.new do
+  # Request inherits all definitions from AuthenticatedRequest.
+  # Any change you make to params, headers, responses or examples will add to
+  # existing definitions.
+end
+```
+
 # Writing tests
 
 Include `Explicit::TestHelper` in your `test/test_helper.rb` or
 `spec/rails_helper.rb`. This module provides the method
-`fetch(request, params:, headers:)` that let's you verify the endpoint works as
+`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.
 
-Add the following line to your `test/test_helper.rb`.
+<details open>
+  <summary>For Minitest users, add the following line to your <code>test/test_helper.rb</code></summary>
 
 ```diff
 module ActiveSupport
@@ -132,13 +165,26 @@ module ActiveSupport
 end
 ```
 
-To test your controller, call `fetch(request, params:, headers:)` and write
-assertions against the response. If the endpoint sends a response that does not
-match expected spec the test fails with
-`Explicit::Request::InvalidResponseError`.
+</details>
+
+<details open>
+  <summary>For RSpec users, add the following line to your <code>spec/rails_helper.rb</code></summary>
+
+```diff
+RSpec.configure do |config|
++  config.include Explicit::TestHelper
+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`.
 
 The response object has a `status`, an integer value for the http status, and
-`data`, a hash with the response data.
+`data`, a hash with the response data. It also provides `dig` for a
+slighly shorter syntax when accessing nested attributes.
 
 > Path params are matched by name, so if you have an endpoint configured with
 > `put "/customers/:customer_id"` you must call as
@@ -147,8 +193,11 @@ The response object has a `status`, an integer value for the http status, and
 > Note: Response specs are only verified in test environment with no
 > performance penalty when running in production.
 
+<details open>
+  <summary>Minitest example</summary>
+
 ```ruby
-class RegistrationsControllerTest < ActionDispatch::IntegrationTest
+class API::V1::RegistrationsControllerTest < ActionDispatch::IntegrationTest
   test "successful registration" do
     response = fetch(RegistrationsController::Request, params: {
       name: "Bilbo Baggins",
@@ -158,54 +207,73 @@ class RegistrationsControllerTest < ActionDispatch::IntegrationTest
     })
 
     assert_equal 200, response.status
+    assert_equal "bilbo@shire.com", response.dig(:user, :email)
+  end
+end
+```
 
-    assert response.data[:id]
-    assert_equal "bilbo@shire.com", response.data[:email]
+</details>
+
+<details open>
+  <summary>RSpec example</summary>
+
+```ruby
+describe RegistrationsController::Request, type: :request do
+  context "when request params are valid" do
+    it "successfully registers a new user" do
+      response = fetch(described_class, params: {
+        name: "Bilbo Baggins",
+        email: "bilbo@shire.com",
+        payment_type: "free_trial",
+        terms_of_use: true
+      })
+
+      expect(response.status).to eql(200)
+      expect(response.dig(:user, :email)).to eql("bilbo@shire.com")
+    end
   end
 end
 ```
 
-# Writing documentation
+</details>
 
-Documentation is written . To make documentation available to users
-you must configure it via `Explicit::Documentation.build` and then publish it
-mounting it in `routes.rb`.
+# Publishing documentation
 
-Inside `Explicit::Documentation.build` you have access to the following methods:
+Call `Explicit::Documentation.new` to group, organize and publish the
+documentation for your API. The following methods are available:
 
-- `page_title(text)`
-- `primary_color(hexcode)`
-- `section(&block)`
-- `add(request)`
-- `add(title:, partial:)`
+- `page_title(text)` - Sets the web page title.
+- `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
 
 For example:
 
 ```ruby
 module MyApp::API::V1
-  Documentation = Explicit::Documentation.build do
-    page_title "Acme Co. | API Docs"
-    primary_color "#6366f1"
+  Documentation = Explicit::Documentation.new do
+    page_title "Acme API Docs"
 
     section "Introduction" do
       add title: "About", partial: "api/v1/introduction/about"
     end
 
     section "Auth" do
-      add SessionsController::CreateRequest
       add RegistrationsController::CreateRequest
+      add SessionsController::CreateRequest
+      add SessionsController::DestroyRequest
     end
 
-    section "Posts" do
-      add PostsController::CreateRequest
-      add PostsController::UpdateRequest
-      add PostsController::DestroyRequest
+    section "Articles" do
+      add ArticlesController::CreateRequest
+      add ArticlesController::UpdateRequest
+      add ArticlesController::DestroyRequest
     end
   end
 end
 ```
 
-`Explicit::Documentation.build` returns a rails engine that you can mount in
+`Explicit::Documentation.new` returns a rails engine that you can mount in
 your `config/routes.rb`. For example:
 
 ```ruby
@@ -214,6 +282,93 @@ Rails.application.routes.draw do
 end
 ```
 
+## Adding request examples
+
+You can add request examples in two different ways:
+
+1. Manually add an example with `add_example(params:, headers:, response:)`
+2. Automatically save examples from tests
+
+### 1. Manually adding examples
+
+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.
+
+For example:
+
+```ruby
+Request = Explicit::Request.new do
+  # ... other configs, params and responses
+
+  add_example(
+    params: {
+      name: "Bilbo baggins",
+      email: "bilbo@shire.com",
+      payment_type: "free_trial",
+      terms_of_use: true
+    }
+    response: {
+      status: 200,
+      data: {
+        user: {
+          id: 15123,
+          email: "bilbo@shire.com"
+        }
+      }
+    }
+  )
+end
+```
+
+Request examples are just data, so you can extract and reference them in any
+way you like. For example:
+
+```ruby
+Request = Explicit::Request.new do
+  # ... other configs, params and responses
+
+  add_example MyApp::Examples::REQUEST_1
+  add_example MyApp::Examples::REQUEST_2
+end
+```
+
+### 2. Automatically saving examples from tests
+
+The `fetch` method provided by `Explicit::TestHelper` accepts the option
+`add_as_example`. When set to true, the request example is persisted to a local
+file. For example:
+
+```ruby
+class RegistrationsControllerTest < ActionDispatch::IntegrationTest
+  test "successful registration" do
+    response = fetch(
+      RegistrationsController::Request,
+      params: {
+        name: "Bilbo Baggins",
+        email: "bilbo@shire.com",
+        payment_type: "free_trial",
+        terms_of_use: true
+      },
+      add_as_example: true # <-- add this line
+    )
+
+    assert_equal 200, response.status
+    assert_equal "bilbo@shire.com", response.dig(:user, :email)
+  end
+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
+[change it here](#request-examples-file-path).
+
+**Important: be careful not to leak any sensitive data when persisting
+examples from tests**
+
 # Specs
 
 ### Agreement
@@ -223,9 +378,9 @@ end
 [:agreement, parse: true]
 ```
 
-The `agreement` type is 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 alongisde `true`: "`true`", `"on"` and `"1"`.
+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`.
 
 ### Array
 
@@ -238,6 +393,18 @@ values are accepted alongisde `true`: "`true`", `"on"` and `"1"`.
 All items in the array must be valid according to the subspec. If at least one
 value is invalid then the array is invalid.
 
+### BigDecimal
+
+```ruby
+:bigdecimal
+[:bigdecimal, min: 0] # inclusive
+[:bigdecimal, max: 100] # inclusive
+```
+
+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
@@ -246,8 +413,8 @@ value is invalid then the array is invalid.
 ```
 
 If `parse: true` is specified then the following values are converted to `true`:
-`"true"`, `"on"` and `"1"`, and the following values are converted to `false`:
-`"false"`, `"off"` and `"0"`.
+`"true"`, `"on"`, `"1"` and `1`, and the following values are converted to
+`false`: `"false"`, `"off"`, `"0"` and `0`.
 
 ### Date Time ISO8601
 
@@ -280,7 +447,20 @@ Provides a default value for the param if the value is not present or it is
 `nil`. Other falsy values such as empty string or zero have precedence over
 the default value.
 
-If you provide a lambda it will execute in every `validate!` call.
+If you provide a lambda it will execute every time `Request.validate!` is
+called.
+
+### Description
+
+```ruby
+[:description, markdown_text, subspec]
+[: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
+and do not affect validation in any way with. There is no overhead at runtime.
+Markdown supported.
 
 ### Hash
 
@@ -293,8 +473,8 @@ If you provide a lambda it will execute in every `validate!` call.
 ```
 
 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 it is
-best to use a [record](#record) instead.
+match valuespec. If you are expecting a hash with a specific set of keys use a
+[record](#record) instead.
 
 ### Inclusion
 
@@ -326,11 +506,11 @@ If `parse: true` is specified then integer encoded string values such as "10" or
 [:literal, value]
 [:literal, 6379]
 [:literal, "value"]
-"value" # literal strings can use shorter syntax
+"value" # strings work like a literal specs, so you can use this shorter syntax.
 ```
 
 A literal value behaves similar to inclusion with a single value. Useful for
-declaring multiple types in `one_of`.
+matching against multiple specs in [`one_of`](#one-of).
 
 ### Nilable
 
@@ -340,7 +520,7 @@ declaring multiple types in `one_of`.
 [:nilable, [:array, :integer]]
 ```
 
-Value must be `nil` or valid according to the subspec.
+Value must either match the subspec or be nil.
 
 ### One of
 
@@ -387,3 +567,46 @@ records with array of records, etc.
 [:string, minlength: 8] # inclusive
 [:string, maxlength: 20] # inclusive
 ```
+
+# Configuration
+
+Add an initializer `config/initializers/explicit.rb` with the following
+code, and then make the desired changes to the config.
+
+```ruby
+Explicit.configure do |config|
+  # change config here...
+end
+```
+
+### Changing examples file path
+
+```ruby
+config.request_examples_file_path = Rails.root.join("public/request_examples.json")
+```
+
+### Customizing error messages
+
+Copy the [default error messages translations](https://github.com/luizpvas/explicit/blob/main/config/locales/en.yml)
+to your project and make the desired changes.
+
+### Customizing error serialization
+
+First disable the default response:
+
+```ruby
+config.rescue_from_invalid_params = false
+```
+
+and then add a custom `rescue_from Explicit::Request::InvalidParamsError` to
+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
+  end
+end
+```

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

@@ -2,9 +2,135 @@
 <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>
-  <h1>Hello world</h1>
+  <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>