sober_swag 0.18.0 → 0.22.0

data/example/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    sober_swag (0.16.0)
+    sober_swag (0.21.0)
       activesupport
       dry-struct (~> 1.0)
       dry-types (~> 1.2)
@@ -9,202 +9,195 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    actioncable (6.0.3.2)
-      actionpack (= 6.0.3.2)
+    actioncable (6.0.4.1)
+      actionpack (= 6.0.4.1)
       nio4r (~> 2.0)
       websocket-driver (>= 0.6.1)
-    actionmailbox (6.0.3.2)
-      actionpack (= 6.0.3.2)
-      activejob (= 6.0.3.2)
-      activerecord (= 6.0.3.2)
-      activestorage (= 6.0.3.2)
-      activesupport (= 6.0.3.2)
+    actionmailbox (6.0.4.1)
+      actionpack (= 6.0.4.1)
+      activejob (= 6.0.4.1)
+      activerecord (= 6.0.4.1)
+      activestorage (= 6.0.4.1)
+      activesupport (= 6.0.4.1)
       mail (>= 2.7.1)
-    actionmailer (6.0.3.2)
-      actionpack (= 6.0.3.2)
-      actionview (= 6.0.3.2)
-      activejob (= 6.0.3.2)
+    actionmailer (6.0.4.1)
+      actionpack (= 6.0.4.1)
+      actionview (= 6.0.4.1)
+      activejob (= 6.0.4.1)
       mail (~> 2.5, >= 2.5.4)
       rails-dom-testing (~> 2.0)
-    actionpack (6.0.3.2)
-      actionview (= 6.0.3.2)
-      activesupport (= 6.0.3.2)
+    actionpack (6.0.4.1)
+      actionview (= 6.0.4.1)
+      activesupport (= 6.0.4.1)
       rack (~> 2.0, >= 2.0.8)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actiontext (6.0.3.2)
-      actionpack (= 6.0.3.2)
-      activerecord (= 6.0.3.2)
-      activestorage (= 6.0.3.2)
-      activesupport (= 6.0.3.2)
+    actiontext (6.0.4.1)
+      actionpack (= 6.0.4.1)
+      activerecord (= 6.0.4.1)
+      activestorage (= 6.0.4.1)
+      activesupport (= 6.0.4.1)
       nokogiri (>= 1.8.5)
-    actionview (6.0.3.2)
-      activesupport (= 6.0.3.2)
+    actionview (6.0.4.1)
+      activesupport (= 6.0.4.1)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activejob (6.0.3.2)
-      activesupport (= 6.0.3.2)
+    activejob (6.0.4.1)
+      activesupport (= 6.0.4.1)
       globalid (>= 0.3.6)
-    activemodel (6.0.3.2)
-      activesupport (= 6.0.3.2)
-    activerecord (6.0.3.2)
-      activemodel (= 6.0.3.2)
-      activesupport (= 6.0.3.2)
-    activestorage (6.0.3.2)
-      actionpack (= 6.0.3.2)
-      activejob (= 6.0.3.2)
-      activerecord (= 6.0.3.2)
-      marcel (~> 0.3.1)
-    activesupport (6.0.3.2)
+    activemodel (6.0.4.1)
+      activesupport (= 6.0.4.1)
+    activerecord (6.0.4.1)
+      activemodel (= 6.0.4.1)
+      activesupport (= 6.0.4.1)
+    activestorage (6.0.4.1)
+      actionpack (= 6.0.4.1)
+      activejob (= 6.0.4.1)
+      activerecord (= 6.0.4.1)
+      marcel (~> 1.0.0)
+    activesupport (6.0.4.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
       zeitwerk (~> 2.2, >= 2.2.2)
-    bootsnap (1.4.6)
+    bootsnap (1.9.3)
       msgpack (~> 1.0)
     builder (3.2.4)
     byebug (11.1.3)
     coderay (1.1.3)
-    concurrent-ruby (1.1.6)
+    concurrent-ruby (1.1.9)
     crass (1.0.6)
     diff-lcs (1.4.4)
-    dry-configurable (0.11.6)
+    dry-configurable (0.13.0)
       concurrent-ruby (~> 1.0)
-      dry-core (~> 0.4, >= 0.4.7)
-      dry-equalizer (~> 0.2)
-    dry-container (0.7.2)
+      dry-core (~> 0.6)
+    dry-container (0.9.0)
       concurrent-ruby (~> 1.0)
-      dry-configurable (~> 0.1, >= 0.1.3)
-    dry-core (0.4.9)
+      dry-configurable (~> 0.13, >= 0.13.0)
+    dry-core (0.7.1)
       concurrent-ruby (~> 1.0)
-    dry-equalizer (0.3.0)
-    dry-inflector (0.2.0)
-    dry-logic (1.0.6)
+    dry-inflector (0.2.1)
+    dry-logic (1.2.0)
       concurrent-ruby (~> 1.0)
-      dry-core (~> 0.2)
-      dry-equalizer (~> 0.2)
-    dry-struct (1.3.0)
-      dry-core (~> 0.4, >= 0.4.4)
-      dry-equalizer (~> 0.3)
-      dry-types (~> 1.3)
+      dry-core (~> 0.5, >= 0.5)
+    dry-struct (1.4.0)
+      dry-core (~> 0.5, >= 0.5)
+      dry-types (~> 1.5)
       ice_nine (~> 0.11)
-    dry-types (1.4.0)
+    dry-types (1.5.1)
       concurrent-ruby (~> 1.0)
       dry-container (~> 0.3)
-      dry-core (~> 0.4, >= 0.4.4)
-      dry-equalizer (~> 0.3)
+      dry-core (~> 0.5, >= 0.5)
       dry-inflector (~> 0.1, >= 0.1.2)
       dry-logic (~> 1.0, >= 1.0.2)
     dry-types-rails (0.3.4)
       dry-types (>= 0.8.1)
       rails (>= 3)
-    erubi (1.9.0)
-    ffi (1.13.1)
-    globalid (0.4.2)
-      activesupport (>= 4.2.0)
-    i18n (1.8.3)
+    erubi (1.10.0)
+    ffi (1.15.4)
+    globalid (1.0.0)
+      activesupport (>= 5.0)
+    i18n (1.8.11)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
-    listen (3.1.5)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-      ruby_dep (~> 1.2)
-    loofah (2.6.0)
+    listen (3.7.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    loofah (2.12.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mail (2.7.1)
       mini_mime (>= 0.1.1)
-    marcel (0.3.3)
-      mimemagic (~> 0.3.2)
+    marcel (1.0.2)
     method_source (1.0.0)
-    mimemagic (0.3.5)
-    mini_mime (1.0.2)
-    mini_portile2 (2.4.0)
-    minitest (5.14.1)
-    msgpack (1.3.3)
-    nio4r (2.5.2)
-    nokogiri (1.10.10)
-      mini_portile2 (~> 2.4.0)
-    pry (0.13.1)
+    mini_mime (1.1.2)
+    mini_portile2 (2.6.1)
+    minitest (5.14.4)
+    msgpack (1.4.2)
+    nio4r (2.5.8)
+    nokogiri (1.12.5)
+      mini_portile2 (~> 2.6.1)
+      racc (~> 1.4)
+    pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    puma (4.3.5)
+    puma (5.5.2)
       nio4r (~> 2.0)
+    racc (1.6.0)
     rack (2.2.3)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
-    rails (6.0.3.2)
-      actioncable (= 6.0.3.2)
-      actionmailbox (= 6.0.3.2)
-      actionmailer (= 6.0.3.2)
-      actionpack (= 6.0.3.2)
-      actiontext (= 6.0.3.2)
-      actionview (= 6.0.3.2)
-      activejob (= 6.0.3.2)
-      activemodel (= 6.0.3.2)
-      activerecord (= 6.0.3.2)
-      activestorage (= 6.0.3.2)
-      activesupport (= 6.0.3.2)
+    rails (6.0.4.1)
+      actioncable (= 6.0.4.1)
+      actionmailbox (= 6.0.4.1)
+      actionmailer (= 6.0.4.1)
+      actionpack (= 6.0.4.1)
+      actiontext (= 6.0.4.1)
+      actionview (= 6.0.4.1)
+      activejob (= 6.0.4.1)
+      activemodel (= 6.0.4.1)
+      activerecord (= 6.0.4.1)
+      activestorage (= 6.0.4.1)
+      activesupport (= 6.0.4.1)
       bundler (>= 1.3.0)
-      railties (= 6.0.3.2)
+      railties (= 6.0.4.1)
       sprockets-rails (>= 2.0.0)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.3.0)
+    rails-html-sanitizer (1.4.2)
       loofah (~> 2.3)
-    railties (6.0.3.2)
-      actionpack (= 6.0.3.2)
-      activesupport (= 6.0.3.2)
+    railties (6.0.4.1)
+      actionpack (= 6.0.4.1)
+      activesupport (= 6.0.4.1)
       method_source
       rake (>= 0.8.7)
       thor (>= 0.20.3, < 2.0)
-    rake (13.0.1)
-    rb-fsevent (0.10.4)
+    rake (13.0.6)
+    rb-fsevent (0.11.0)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rspec-core (3.9.2)
-      rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.2)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-rails (4.0.1)
-      actionpack (>= 4.2)
-      activesupport (>= 4.2)
-      railties (>= 4.2)
-      rspec-core (~> 3.9)
-      rspec-expectations (~> 3.9)
-      rspec-mocks (~> 3.9)
-      rspec-support (~> 3.9)
-    rspec-support (3.9.3)
-    ruby_dep (1.5.0)
-    spring (2.1.0)
+      rspec-support (~> 3.10.0)
+    rspec-rails (5.0.2)
+      actionpack (>= 5.2)
+      activesupport (>= 5.2)
+      railties (>= 5.2)
+      rspec-core (~> 3.10)
+      rspec-expectations (~> 3.10)
+      rspec-mocks (~> 3.10)
+      rspec-support (~> 3.10)
+    rspec-support (3.10.3)
+    spring (2.1.1)
     spring-watcher-listen (2.0.1)
       listen (>= 2.7, < 4.0)
       spring (>= 1.2, < 3.0)
     sprockets (4.0.2)
       concurrent-ruby (~> 1.0)
       rack (> 1, < 3)
-    sprockets-rails (3.2.1)
-      actionpack (>= 4.0)
-      activesupport (>= 4.0)
+    sprockets-rails (3.4.1)
+      actionpack (>= 5.2)
+      activesupport (>= 5.2)
       sprockets (>= 3.0.0)
     sqlite3 (1.4.2)
-    thor (1.0.1)
+    thor (1.1.0)
     thread_safe (0.3.6)
-    tzinfo (1.2.7)
+    tzinfo (1.2.9)
       thread_safe (~> 0.1)
-    websocket-driver (0.7.3)
+    websocket-driver (0.7.5)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
-    zeitwerk (2.4.0)
+    zeitwerk (2.5.1)
 
 PLATFORMS
   ruby
@@ -214,9 +207,9 @@ DEPENDENCIES
   bootsnap (>= 1.4.2)
   byebug
   dry-types-rails
-  listen (>= 3.0.5, < 3.2)
+  listen (>= 3.0.5, < 3.8)
   pry
-  puma (~> 4.3)
+  puma (~> 5.4)
   rails (~> 6.0.2, >= 6.0.2.2)
   rspec-rails
   sober_swag!

data/example/app/controllers/application_controller.rb

@@ -4,4 +4,8 @@ class ApplicationController < ActionController::API
   rescue_from Dry::Struct::Error do
     head :bad_request
   end
+
+  rescue_from SoberSwag::Reporting::Report::Error do |error|
+    render json: error.report.path_hash, status: :bad_request
+  end
 end

data/example/app/controllers/people_controller.rb

@@ -5,35 +5,40 @@ class PeopleController < ApplicationController
 
   before_action :load_person, only: %i[show update]
 
-  PersonBodyParams = SoberSwag.input_object do
-    identifier 'PersonBodyParams'
+  ##
+  # Parameters to create or update a person.
+  class ReportingPersonParams < SoberSwag::Reporting::Input::Struct
+    identifier 'PersonReportingParams'
 
-    attribute :first_name, SoberSwag::Types::String
-    attribute :last_name, SoberSwag::Types::String
-    attribute? :date_of_birth, SoberSwag::Types::Params::DateTime.optional
+    attribute :first_name, SoberSwag::Reporting::Input::Text.new.with_pattern(/.+/)
+    attribute :last_name, SoberSwag::Reporting::Input::Text.new.with_pattern(/.+/)
+    attribute? :date_of_birth, SoberSwag::Reporting::Input::Converting::DateTime.optional
   end
 
-  PersonBodyPatchParams = SoberSwag.input_object(PersonBodyParams) do
-    identifier 'PersonBodyPatchParams'
+  ##
+  # Parameters to create a person.
+  class ReportingPersonCreate < SoberSwag::Reporting::Input::Struct
+    identifier 'ReportingPersonCreate'
 
-    attribute? :first_name, SoberSwag::Types::String
-    attribute? :last_name, SoberSwag::Types::String
-    attribute? :date_of_birth, SoberSwag::Types::Params::DateTime.optional
+    attribute :person, ReportingPersonParams
   end
 
-  PersonParams = SoberSwag.input_object do
-    identifier 'PersonParams'
-    attribute :person, PersonBodyParams
-  end
+  ##
+  # Patch body for a person.
+  class ReportingPersonPatchParams < SoberSwag::Reporting::Input::Struct
+    identifier 'PersonReportingPatchParams'
 
-  PersonPatchParams = SoberSwag.input_object do
-    identifier 'PersonPatchParams'
-    attribute :person, PersonBodyPatchParams
+    attribute? :first_name, SoberSwag::Reporting::Input.text.with_pattern(/.+/)
+    attribute? :last_name, SoberSwag::Reporting::Input.text.with_pattern(/.+/)
+    attribute? :date_of_birth, SoberSwag::Reporting::Input::Converting::DateTime.optional
   end
 
   define :post, :create, '/people/' do
-    request_body(PersonParams)
+    summary 'Create a person'
+
+    request_body(ReportingPersonCreate)
     response(:ok, 'the person created', PersonOutputObject)
+    response(:bad_request, 'the parse errors', SoberSwag::Reporting::Report::Output)
     response(:unprocessable_entity, 'the validation errors', PersonErrorsOutputObject)
     tags 'people', 'create'
   end
@@ -47,9 +52,14 @@ class PeopleController < ApplicationController
   end
 
   define :patch, :update, '/people/{id}' do
-    request_body(PersonPatchParams)
-    path_params { attribute :id, Types::Params::Integer }
+    summary 'Update a person'
+
+    request_body(reporting: true) do
+      attribute :person, ReportingPersonPatchParams
+    end
+    path_params(reporting: true) { attribute :id, SoberSwag::Reporting::Input::Converting::Integer }
     response(:ok, 'the person updated', PersonOutputObject)
+    response(:bad_request, 'the parse errors', SoberSwag::Reporting::Report::Output)
     response(:unprocessable_entity, 'the validation errors', PersonErrorsOutputObject)
     tags 'people', 'update'
   end
@@ -62,28 +72,34 @@ class PeopleController < ApplicationController
   end
 
   define :get, :index, '/people/' do
-    query_params do
+    summary 'List persons'
+
+    query_params(reporting: true) do
       attribute? :filters do
-        attribute? :first_name, Types::String
-        attribute? :last_name, Types::String
+        attribute? :first_name, SoberSwag::Reporting::Input.text
+        attribute? :last_name, SoberSwag::Reporting::Input.text
       end
-      attribute :view, Types::String.default('base'.freeze).enum('base', 'detail')
+      attribute? :view, SoberSwag::Reporting::Input.text.enum('base', 'detail')
     end
-    response(:ok, 'all the people', PersonOutputObject.array)
+    response(:ok, 'all the people', PersonOutputObject.list)
+    response(:bad_request, 'the parse errors', SoberSwag::Reporting::Report::Output)
     tags 'people', 'list'
   end
   def index
     @people = Person.all
     @people = @people.where('UPPER(first_name) LIKE UPPER(?)', "%#{parsed_query.filters.first_name}%") if parsed_query.filters&.first_name
     @people = @people.where('UPPER(last_name) LIKE UPPER(?)', "%#{parsed_query.filters.last_name}%") if parsed_query.filters&.last_name
-    respond!(:ok, @people.includes(:posts), serializer_opts: { view: parsed_query.view })
+    respond!(:ok, @people.includes(:posts), serializer_opts: { view: parsed_query.view || :base })
   end
 
   define :get, :show, '/people/{id}' do
-    path_params do
-      attribute :id, Types::Params::Integer
+    summary 'Get a single person by id'
+
+    path_params(reporting: true) do
+      attribute :id, SoberSwag::Reporting::Input::Converting::Integer
     end
     response(:ok, 'the person requested', PersonOutputObject)
+    response(:bad_request, 'the parse errors', SoberSwag::Reporting::Report::Output)
     tags 'people', 'show'
   end
   def show

data/example/app/output_objects/identified_output.rb

@@ -0,0 +1,7 @@
+##
+# Base serializer for objects with a global id of some variety.
+class IdentifiedOutput < SoberSwag::Reporting::Output::Struct
+  field :global_id, SoberSwag::Reporting::Output.text.nilable do
+    object_to_serialize.try(:to_global_id).try(:to_s)
+  end
+end

data/example/app/output_objects/person_output_object.rb

@@ -1,15 +1,41 @@
-PersonOutputObject = SoberSwag::OutputObject.define do
-  identifier 'Person'
-  field :id, primitive(:Integer).meta(description: 'Unique ID')
-  field :first_name, primitive(:String).meta(description: <<~MARKDOWN)
-    This is the first name of a person.
-    Note that you can't use this as a unique identifier, and you really should understand how names work before using this.
-    [Falsehoods programmers believe about names](https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/)
-    is a good thing to read!
+##
+# Output object that serializes a person.
+class PersonOutputObject < IdentifiedOutput
+  identifier 'PersonOutput'
+
+  description <<~MARKDOWN
+    Basic as hell serializer for a person.
   MARKDOWN
-  field :last_name, primitive(:String)
 
-  view :detail do
-    field :posts, -> { PostOutputObject.array }
+  field :id, SoberSwag::Reporting::Output::Text.new.via_map(&:to_s)
+  field(
+    :first_name,
+    SoberSwag::Reporting::Output::Text.new,
+    description: <<~MARKDOWN
+      This is the first name of a person.
+      Note that you can't use this as a unique identifier, and you really should understand how names work before using this.
+      [Falsehoods programmers believe about names](https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/)
+      is a good thing to read!
+    MARKDOWN
+  )
+  field(
+    :last_name, SoberSwag::Reporting::Output::Text.new
+  )
+
+  define_view :detail do
+    field(
+      :initials,
+      SoberSwag::Reporting::Output::Text.new
+    ) do |person|
+      [person.first_name[0..0], person.last_name[0..0]].compact.map { |x| "#{x}." }.join(' ')
+    end
+
+    field(
+      :posts,
+      SoberSwag::Reporting::Output::Defer.defer do
+        ReportingPostOutput.view(:base).array
+      end,
+      description: 'all posts this user has made'
+    )
   end
 end

data/example/app/output_objects/post_output_object.rb

@@ -3,8 +3,4 @@ PostOutputObject = SoberSwag::OutputObject.define do
   field :id, primitive(:Integer)
   field :title, primitive(:String)
   field :body, primitive(:String)
-
-  view :detail do
-    field :person, -> { PersonOutputObject.view(:base) }
-  end
 end

data/example/app/output_objects/reporting_post_output.rb

@@ -0,0 +1,18 @@
+##
+# A reporting output object for a post.
+class ReportingPostOutput < SoberSwag::Reporting::Output::Struct
+  identifier 'ReportingPostOutput'
+
+  field :id, SoberSwag::Reporting::Output::Text.new.via_map(&:to_s)
+  field :title, SoberSwag::Reporting::Output::Text.new
+  field :body, SoberSwag::Reporting::Output::Text.new
+
+  define_view :detail do
+    field(
+      :person,
+      SoberSwag::Reporting::Output::Defer.defer do
+        PersonOutputObject.view(:base)
+      end
+    )
+  end
+end

data/example/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/example/config/environments/production.rb

@@ -60,7 +60,7 @@ Rails.application.configure do
   # config.logger = ActiveSupport::TaggedLogging.new(Syslog::Logger.new 'app-name')
 
   if ENV['RAILS_LOG_TO_STDOUT'].present?
-    logger           = ActiveSupport::Logger.new(STDOUT)
+    logger           = ActiveSupport::Logger.new($stdout)
     logger.formatter = config.log_formatter
     config.logger    = ActiveSupport::TaggedLogging.new(logger)
   end

data/example/spec/requests/people/create_spec.rb

@@ -34,7 +34,8 @@ RSpec.describe 'people controller create', type: :request do
 
       it { should_not be_successful }
       it { should_not be_server_error }
-      it { should be_unprocessable }
+      it { should be_bad_request }
+      it { should have_attributes(status: 400) }
     end
 
     describe 'the act of requesting' do
@@ -46,7 +47,7 @@ RSpec.describe 'people controller create', type: :request do
     describe 'the response body' do
       subject { request && response && JSON.parse(response.body) }
 
-      it { should have_key('first_name') }
+      it { should have_key('$.person.first_name') }
     end
   end
 end

data/example/spec/requests/people/index_spec.rb

@@ -30,7 +30,7 @@ RSpec.describe 'Index action for people' do
       end
 
       it 'has the right person' do
-        expect(parsed_body).to include(include('id' => person.id))
+        expect(parsed_body).to include(include('id' => person.id.to_s))
       end
     end